1use std::cmp::Ordering;
7use std::hash::Hash;
8use std::hash::Hasher;
9
10use vortex_error::VortexResult;
11use vortex_error::vortex_ensure_eq;
12use vortex_error::vortex_err;
13use vortex_error::vortex_panic;
14
15use crate::dtype::DType;
16use crate::dtype::NativeDType;
17use crate::dtype::PType;
18use crate::dtype::StructFields;
19use crate::dtype::half::f16;
20use crate::scalar::PValue;
21use crate::scalar::Scalar;
22use crate::scalar::ScalarValue;
23
24impl Scalar {
25 pub fn null(dtype: DType) -> Self {
33 assert!(
34 dtype.is_nullable(),
35 "Cannot create null scalar with non-nullable dtype {dtype}"
36 );
37
38 Self { dtype, value: None }
39 }
40
41 pub fn null_native<T: NativeDType>() -> Self {
46 Self {
47 dtype: T::dtype().as_nullable(),
48 value: None,
49 }
50 }
51
52 #[cfg(test)]
62 pub fn new(dtype: DType, value: Option<ScalarValue>) -> Self {
63 use vortex_error::VortexExpect;
64
65 Self::try_new(dtype, value).vortex_expect("Failed to create Scalar")
66 }
67
68 #[inline]
78 pub fn try_new(dtype: DType, value: Option<ScalarValue>) -> VortexResult<Self> {
79 if Self::is_compatible(&dtype, value.as_ref()) {
80 return Ok(Self { dtype, value });
81 }
82
83 Self::try_new_fallback(dtype, value)
84 }
85
86 #[cold]
90 #[inline(never)]
91 fn try_new_fallback(dtype: DType, value: Option<ScalarValue>) -> VortexResult<Self> {
92 let value = match (&dtype, value) {
93 (DType::Primitive(PType::F16, _), Some(ScalarValue::Primitive(PValue::U64(bits)))) => {
94 let bits = u16::try_from(bits).map_err(|_| {
95 vortex_err!("f16 bit representation must fit in 16 bits, got {bits}")
96 })?;
97
98 Some(ScalarValue::Primitive(PValue::F16(f16::from_bits(bits))))
99 }
100 (_, value) => return Err(Self::incompatible_error(&dtype, value.as_ref())),
101 };
102
103 Ok(Self { dtype, value })
104 }
105
106 pub unsafe fn new_unchecked(dtype: DType, value: Option<ScalarValue>) -> Self {
114 #[cfg(debug_assertions)]
115 {
116 use vortex_error::VortexExpect;
117
118 Self::validate(&dtype, value.as_ref())
119 .vortex_expect("Scalar::new_unchecked called with incompatible dtype and value");
120 }
121
122 Self { dtype, value }
123 }
124
125 pub fn default_value(dtype: &DType) -> Self {
144 Self::try_default_value(dtype)
145 .unwrap_or_else(|| vortex_panic!("{dtype} has no default value"))
146 }
147
148 pub(crate) fn try_default_value(dtype: &DType) -> Option<Self> {
150 let value = ScalarValue::try_default_value(dtype)?;
151 Self::try_new(dtype.clone(), value).ok()
152 }
153
154 pub fn zero_value(dtype: &DType) -> Self {
184 let value = ScalarValue::zero_value(dtype);
185
186 Self::try_new(dtype.clone(), Some(value))
187 .unwrap_or_else(|error| vortex_panic!("{dtype} has no non-null zero value: {error}"))
188 }
189
190 pub fn eq_ignore_nullability(&self, other: &Self) -> bool {
194 self.dtype.eq_ignore_nullability(&other.dtype) && self.value == other.value
195 }
196
197 pub fn into_parts(self) -> (DType, Option<ScalarValue>) {
199 (self.dtype, self.value)
200 }
201
202 pub fn dtype(&self) -> &DType {
204 &self.dtype
205 }
206
207 pub fn value(&self) -> Option<&ScalarValue> {
209 self.value.as_ref()
210 }
211
212 pub fn into_value(self) -> Option<ScalarValue> {
215 self.value
216 }
217
218 pub fn is_valid(&self) -> bool {
220 self.value.is_some()
221 }
222
223 pub fn is_null(&self) -> bool {
225 self.value.is_none()
226 }
227
228 pub fn is_zero(&self) -> Option<bool> {
237 let value = self.value()?;
238
239 let is_zero = match self.dtype() {
240 DType::Null => {
241 vortex_panic!("non-null value somehow had `DType::Null`")
242 }
243 DType::Bool(_) => !value.as_bool(),
244 DType::Primitive(..) => value.as_primitive().is_zero(),
245 DType::Decimal(..) => value.as_decimal().is_zero(),
246 DType::Utf8(_) => value.as_utf8().is_empty(),
247 DType::Binary(_) => value.as_binary().is_empty(),
248 DType::List(..) => value.as_list().is_empty(),
249 DType::Map(..) => self.as_map().is_empty(),
250 DType::FixedSizeList(_, list_size, _) => {
253 let list = self.as_list();
254 list.len() == *list_size as usize
255 && (0..list.len())
256 .all(|i| list.element(i).is_some_and(|e| e.is_zero() == Some(true)))
257 }
258 DType::Struct(..) => self
260 .as_struct()
261 .fields_iter()
262 .is_some_and(|mut fields| fields.all(|f| f.is_zero() == Some(true))),
263 DType::Union(..) => {
266 let union = self.as_union();
267 if union.child_index() != Some(0) {
268 false
269 } else {
270 union.child().and_then(|child| child.is_zero())?
271 }
272 }
273 DType::Variant(_) => self.as_variant().is_zero()?,
274 DType::Extension(_) => self.as_extension().to_storage_scalar().is_zero()?,
275 };
276
277 Some(is_zero)
278 }
279
280 pub fn primitive_reinterpret_cast(&self, ptype: PType) -> VortexResult<Self> {
286 let primitive = self.as_primitive();
287 if primitive.ptype() == ptype {
288 return Ok(self.clone());
289 }
290
291 vortex_ensure_eq!(
292 primitive.ptype().byte_width(),
293 ptype.byte_width(),
294 "can't reinterpret cast between integers of two different widths"
295 );
296
297 Scalar::try_new(
298 DType::Primitive(ptype, self.dtype().nullability()),
299 primitive
300 .pvalue()
301 .map(|p| p.reinterpret_cast(ptype))
302 .map(ScalarValue::Primitive),
303 )
304 }
305
306 pub fn approx_nbytes(&self) -> usize {
311 use crate::dtype::NativeDecimalType;
312 use crate::dtype::i256;
313
314 match self.dtype() {
315 DType::Null => 0,
316 DType::Bool(_) => 1,
317 DType::Primitive(ptype, _) => ptype.byte_width(),
318 DType::Decimal(dt, _) => {
319 if dt.precision() <= i128::MAX_PRECISION {
320 size_of::<i128>()
321 } else {
322 size_of::<i256>()
323 }
324 }
325 DType::Utf8(_) => self
326 .value()
327 .map_or_else(|| 0, |value| value.as_utf8().len()),
328 DType::Binary(_) => self
329 .value()
330 .map_or_else(|| 0, |value| value.as_binary().len()),
331 DType::List(..) | DType::FixedSizeList(..) => self
332 .as_list()
333 .elements()
334 .map(|fields| fields.into_iter().map(|f| f.approx_nbytes()).sum::<usize>())
335 .unwrap_or_default(),
336 DType::Map(..) => self
337 .as_map()
338 .entries()
339 .map(|(key, value)| key.approx_nbytes() + value.approx_nbytes())
340 .sum(),
341 DType::Struct(..) => self
342 .as_struct()
343 .fields_iter()
344 .map(|fields| fields.into_iter().map(|f| f.approx_nbytes()).sum::<usize>())
345 .unwrap_or_default(),
346 DType::Union(..) => self
347 .as_union()
348 .child()
349 .map_or(0, |value| 1 + value.approx_nbytes()),
350 DType::Variant(_) => self.as_variant().value().map_or(0, Scalar::approx_nbytes),
351 DType::Extension(_) => self.as_extension().to_storage_scalar().approx_nbytes(),
352 }
353 }
354}
355
356impl Hash for Scalar {
360 fn hash<H: Hasher>(&self, state: &mut H) {
361 self.dtype.hash_ignore_nullability(state);
362 self.value.hash(state);
363 }
364}
365
366impl PartialEq for Scalar {
373 fn eq(&self, other: &Self) -> bool {
374 self.dtype.eq_ignore_nullability(&other.dtype) && self.value == other.value
375 }
376}
377
378impl PartialOrd for Scalar {
379 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
415 if !self.dtype().eq_ignore_nullability(other.dtype()) {
416 return None;
417 }
418
419 partial_cmp_scalar_values(self.dtype(), self.value(), other.value())
420 }
421}
422
423fn partial_cmp_scalar_values(
425 dtype: &DType,
426 lhs: Option<&ScalarValue>,
427 rhs: Option<&ScalarValue>,
428) -> Option<Ordering> {
429 match (lhs, rhs) {
430 (None, None) => Some(Ordering::Equal),
431 (None, Some(_)) => Some(Ordering::Less),
432 (Some(_), None) => Some(Ordering::Greater),
433 (Some(lhs), Some(rhs)) => partial_cmp_non_null_scalar_values(dtype, lhs, rhs),
434 }
435}
436
437fn partial_cmp_non_null_scalar_values(
439 dtype: &DType,
440 lhs: &ScalarValue,
441 rhs: &ScalarValue,
442) -> Option<Ordering> {
443 match (lhs, rhs) {
446 (ScalarValue::Bool(lhs), ScalarValue::Bool(rhs)) => lhs.partial_cmp(rhs),
447 (ScalarValue::Primitive(lhs), ScalarValue::Primitive(rhs)) => lhs.partial_cmp(rhs),
448 (ScalarValue::Decimal(lhs), ScalarValue::Decimal(rhs)) => lhs.partial_cmp(rhs),
449 (ScalarValue::Utf8(lhs), ScalarValue::Utf8(rhs)) => lhs.partial_cmp(rhs),
450 (ScalarValue::Binary(lhs), ScalarValue::Binary(rhs)) => lhs.partial_cmp(rhs),
451 (ScalarValue::Tuple(lhs), ScalarValue::Tuple(rhs)) => {
454 partial_cmp_tuple_values(dtype, lhs, rhs)
455 }
456 (ScalarValue::Union(lhs), ScalarValue::Union(rhs)) => {
457 if lhs.type_id() != rhs.type_id() {
458 return None;
459 }
460
461 let DType::Union(variants, _) = dtype else {
462 return None;
463 };
464 let child_index = variants.tag_to_child_index(lhs.type_id())?;
465 let child_dtype = variants.variant_by_index(child_index)?;
466
467 partial_cmp_scalar_values(&child_dtype, lhs.child_value(), rhs.child_value())
468 }
469 (ScalarValue::Variant(_), ScalarValue::Variant(_)) => None,
472 _ => None,
473 }
474}
475
476fn partial_cmp_tuple_values(
478 dtype: &DType,
479 lhs: &[Option<ScalarValue>],
480 rhs: &[Option<ScalarValue>],
481) -> Option<Ordering> {
482 match dtype {
483 DType::List(element_dtype, _) | DType::FixedSizeList(element_dtype, ..) => {
484 partial_cmp_list_values(element_dtype, lhs, rhs)
485 }
486 DType::Struct(fields, _) => partial_cmp_struct_values(fields, lhs, rhs),
487 DType::Map(map_dtype, _) => partial_cmp_list_values(&map_dtype.entries_dtype(), lhs, rhs),
489 DType::Extension(ext_dtype) => {
490 partial_cmp_tuple_values(ext_dtype.storage_dtype(), lhs, rhs)
491 }
492 _ => None,
493 }
494}
495
496fn partial_cmp_list_values(
498 element_dtype: &DType,
499 lhs: &[Option<ScalarValue>],
500 rhs: &[Option<ScalarValue>],
501) -> Option<Ordering> {
502 for (lhs, rhs) in lhs.iter().zip(rhs.iter()) {
503 match partial_cmp_scalar_values(element_dtype, lhs.as_ref(), rhs.as_ref())? {
504 Ordering::Equal => continue,
505 ordering => return Some(ordering),
506 }
507 }
508
509 Some(lhs.len().cmp(&rhs.len()))
510}
511
512fn partial_cmp_struct_values(
514 fields: &StructFields,
515 lhs: &[Option<ScalarValue>],
516 rhs: &[Option<ScalarValue>],
517) -> Option<Ordering> {
518 if lhs.len() != fields.nfields() || rhs.len() != fields.nfields() {
519 return None;
520 }
521
522 for ((field_dtype, lhs), rhs) in fields.field_dtypes().zip(lhs.iter()).zip(rhs.iter()) {
523 match partial_cmp_scalar_values(field_dtype, lhs.as_ref(), rhs.as_ref())? {
524 Ordering::Equal => continue,
525 ordering => return Some(ordering),
526 }
527 }
528
529 Some(Ordering::Equal)
530}
531
532#[cfg(test)]
533mod tests {
534 use std::cmp::Ordering;
535 use std::sync::Arc;
536
537 use rstest::rstest;
538 use vortex_error::VortexResult;
539
540 use crate::dtype::DType;
541 use crate::dtype::Nullability;
542 use crate::dtype::PType;
543 use crate::dtype::StructFields;
544 use crate::scalar::Scalar;
545
546 fn i32_scalar(value: i32) -> Scalar {
547 Scalar::primitive::<i32>(value, Nullability::NonNullable)
548 }
549
550 fn nullable_i32(value: Option<i32>) -> Scalar {
551 match value {
552 Some(value) => Scalar::primitive::<i32>(value, Nullability::Nullable),
553 None => Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable)),
554 }
555 }
556
557 fn map_dtype(nullability: Nullability) -> VortexResult<DType> {
558 DType::map(
559 DType::Primitive(PType::I32, Nullability::NonNullable),
560 DType::Utf8(Nullability::Nullable),
561 false,
562 nullability,
563 )
564 }
565
566 fn map_scalar(entries: Vec<(i32, Option<&str>)>) -> VortexResult<Scalar> {
567 Scalar::try_map(
568 map_dtype(Nullability::Nullable)?,
569 entries.into_iter().map(|(key, value)| {
570 (
571 i32_scalar(key),
572 match value {
573 Some(value) => Scalar::utf8(value, Nullability::Nullable),
574 None => Scalar::null(DType::Utf8(Nullability::Nullable)),
575 },
576 )
577 }),
578 )
579 }
580
581 #[rstest]
583 #[case(vec![(1, Some("a"))], vec![(1, Some("a"))], Ordering::Equal)]
584 #[case(vec![(1, Some("a"))], vec![(1, Some("b"))], Ordering::Less)]
585 #[case(vec![(2, Some("a"))], vec![(1, Some("z"))], Ordering::Greater)]
586 #[case(vec![(1, Some("a"))], vec![(1, Some("a")), (2, Some("b"))], Ordering::Less)]
587 #[case(vec![], vec![], Ordering::Equal)]
588 #[case(vec![], vec![(1, Some("a"))], Ordering::Less)]
589 #[case(vec![(1, Some("a"))], vec![(1, None)], Ordering::Greater)]
590 fn map_ordering(
591 #[case] lhs: Vec<(i32, Option<&str>)>,
592 #[case] rhs: Vec<(i32, Option<&str>)>,
593 #[case] expected: Ordering,
594 ) -> VortexResult<()> {
595 assert_eq!(
596 map_scalar(lhs)?.partial_cmp(&map_scalar(rhs)?),
597 Some(expected)
598 );
599 Ok(())
600 }
601
602 #[test]
603 fn null_map_orders_before_every_non_null_map() -> VortexResult<()> {
604 let null = Scalar::null(map_dtype(Nullability::Nullable)?);
605
606 assert_eq!(null.partial_cmp(&map_scalar(vec![])?), Some(Ordering::Less));
607 assert_eq!(null.partial_cmp(&null), Some(Ordering::Equal));
608
609 Ok(())
610 }
611
612 fn ab_struct_dtype(nullability: Nullability) -> DType {
613 DType::Struct(
614 StructFields::new(
615 ["a", "b"].into(),
616 vec![
617 DType::Primitive(PType::I32, Nullability::NonNullable),
618 DType::Utf8(Nullability::NonNullable),
619 ],
620 ),
621 nullability,
622 )
623 }
624
625 #[rstest]
626 #[case(vec![0, 0], Some(true))]
628 #[case(vec![0], Some(true))]
629 #[case(vec![0, 5], Some(false))]
632 #[case(vec![5, 0], Some(false))]
633 #[case(vec![1, 2], Some(false))]
634 fn fixed_size_list_is_zero(#[case] values: Vec<i32>, #[case] expected: Option<bool>) {
635 let element_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
636 let children: Vec<Scalar> = values.into_iter().map(i32_scalar).collect();
637 let scalar = Scalar::fixed_size_list(element_dtype, children, Nullability::NonNullable);
638 assert_eq!(scalar.is_zero(), expected);
639 }
640
641 #[test]
642 fn null_fixed_size_list_is_zero_is_none() {
643 let element_dtype = Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
644 let scalar = Scalar::null(DType::FixedSizeList(
645 element_dtype,
646 2,
647 Nullability::Nullable,
648 ));
649 assert_eq!(scalar.is_zero(), None);
650 }
651
652 #[test]
653 fn fixed_size_list_with_null_element_is_not_zero() {
654 let element_dtype = DType::Primitive(PType::I32, Nullability::Nullable);
657 let children = vec![nullable_i32(Some(0)), nullable_i32(None)];
658 let scalar = Scalar::fixed_size_list(element_dtype, children, Nullability::NonNullable);
659 assert_eq!(scalar.is_zero(), Some(false));
660 }
661
662 #[test]
663 fn struct_with_all_zero_fields_is_zero() {
664 let scalar = Scalar::struct_(
665 ab_struct_dtype(Nullability::NonNullable),
666 vec![i32_scalar(0), Scalar::utf8("", Nullability::NonNullable)],
667 );
668 assert_eq!(scalar.is_zero(), Some(true));
669 }
670
671 #[rstest]
672 #[case(5, "")]
675 #[case(0, "x")]
676 #[case(7, "y")]
677 fn struct_with_non_zero_field_is_not_zero(#[case] a: i32, #[case] b: &str) {
678 let scalar = Scalar::struct_(
679 ab_struct_dtype(Nullability::NonNullable),
680 vec![i32_scalar(a), Scalar::utf8(b, Nullability::NonNullable)],
681 );
682 assert_eq!(scalar.is_zero(), Some(false));
683 }
684
685 #[test]
686 fn null_struct_is_zero_is_none() {
687 let scalar = Scalar::null(ab_struct_dtype(Nullability::Nullable));
688 assert_eq!(scalar.is_zero(), None);
689 }
690
691 #[test]
692 fn struct_with_null_field_is_not_zero() {
693 let dtype = DType::Struct(
696 StructFields::new(
697 ["a", "b"].into(),
698 vec![
699 DType::Primitive(PType::I32, Nullability::Nullable),
700 DType::Primitive(PType::I32, Nullability::Nullable),
701 ],
702 ),
703 Nullability::NonNullable,
704 );
705 let scalar = Scalar::struct_(dtype, vec![nullable_i32(Some(0)), nullable_i32(None)]);
706 assert_eq!(scalar.is_zero(), Some(false));
707 }
708
709 #[test]
710 fn nested_struct_of_fixed_size_list_recurses() {
711 let element_dtype = Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
714 let fsl_dtype =
715 DType::FixedSizeList(Arc::clone(&element_dtype), 2, Nullability::NonNullable);
716 let struct_dtype = DType::Struct(
717 StructFields::new(["fsl"].into(), vec![fsl_dtype]),
718 Nullability::NonNullable,
719 );
720
721 let all_zero = Scalar::struct_(
722 struct_dtype.clone(),
723 vec![Scalar::fixed_size_list(
724 Arc::clone(&element_dtype),
725 vec![i32_scalar(0), i32_scalar(0)],
726 Nullability::NonNullable,
727 )],
728 );
729 assert_eq!(all_zero.is_zero(), Some(true));
730
731 let with_non_zero = Scalar::struct_(
732 struct_dtype,
733 vec![Scalar::fixed_size_list(
734 element_dtype,
735 vec![i32_scalar(0), i32_scalar(9)],
736 Nullability::NonNullable,
737 )],
738 );
739 assert_eq!(with_non_zero.is_zero(), Some(false));
740 }
741}