pub struct Scalar { /* private fields */ }Expand description
A single logical item, composed of both a ScalarValue and a logical DType.
A ScalarValue is opaque, and should be accessed via one of the type-specific scalar wrappers
for example BoolScalar, PrimitiveScalar, etc.
Note that PartialOrd is implemented only for an exact match of the scalar’s dtype,
including nullability. When the DType does match, ordering is nulls first (lowest), then the
natural ordering of the scalar value.
Implementations§
Source§impl Scalar
impl Scalar
Sourcepub fn binary(buffer: impl Into<ByteBuffer>, nullability: Nullability) -> Self
pub fn binary(buffer: impl Into<ByteBuffer>, nullability: Nullability) -> Self
Creates a new binary scalar from a byte buffer.
Source§impl Scalar
impl Scalar
Sourcepub fn bool(value: bool, nullability: Nullability) -> Self
pub fn bool(value: bool, nullability: Nullability) -> Self
Creates a new boolean scalar with the given value and nullability.
Source§impl Scalar
impl Scalar
Sourcepub fn decimal(
value: DecimalValue,
decimal_type: DecimalDType,
nullability: Nullability,
) -> Self
pub fn decimal( value: DecimalValue, decimal_type: DecimalDType, nullability: Nullability, ) -> Self
Creates a new decimal scalar with the given value, precision, scale, and nullability.
Source§impl Scalar
impl Scalar
Sourcepub fn list(
element_dtype: impl Into<Arc<DType>>,
children: Vec<Scalar>,
nullability: Nullability,
) -> Self
pub fn list( element_dtype: impl Into<Arc<DType>>, children: Vec<Scalar>, nullability: Nullability, ) -> Self
Creates a new list scalar with the given element type and children.
§Panics
Panics if any child scalar has a different type than the element type.
Sourcepub fn list_empty(element_dtype: Arc<DType>, nullability: Nullability) -> Self
pub fn list_empty(element_dtype: Arc<DType>, nullability: Nullability) -> Self
Creates a new empty list scalar with the given element type.
Source§impl Scalar
impl Scalar
Sourcepub fn primitive<T: NativePType + Into<PValue>>(
value: T,
nullability: Nullability,
) -> Self
pub fn primitive<T: NativePType + Into<PValue>>( value: T, nullability: Nullability, ) -> Self
Creates a new primitive scalar from a native value.
Sourcepub fn primitive_value(
value: PValue,
ptype: PType,
nullability: Nullability,
) -> Self
pub fn primitive_value( value: PValue, ptype: PType, nullability: Nullability, ) -> Self
Create a PrimitiveScalar from a PValue.
Note that an explicit PType is passed since any compatible PValue may be used as the value for a primitive type.
Sourcepub fn reinterpret_cast(&self, ptype: PType) -> Self
pub fn reinterpret_cast(&self, ptype: PType) -> Self
Reinterprets the bytes of this scalar as a different primitive type.
§Panics
Panics if the scalar is not a primitive type or if the types have different byte widths.
Source§impl Scalar
impl Scalar
Sourcepub fn utf8<B>(str: B, nullability: Nullability) -> Selfwhere
B: Into<BufferString>,
pub fn utf8<B>(str: B, nullability: Nullability) -> Selfwhere
B: Into<BufferString>,
Creates a new UTF-8 scalar from a string-like value.
§Panics
Panics if the input cannot be converted to a valid UTF-8 string.
Sourcepub fn try_utf8<B>(
str: B,
nullability: Nullability,
) -> Result<Self, <B as TryInto<BufferString>>::Error>where
B: TryInto<BufferString>,
pub fn try_utf8<B>(
str: B,
nullability: Nullability,
) -> Result<Self, <B as TryInto<BufferString>>::Error>where
B: TryInto<BufferString>,
Tries to create a new UTF-8 scalar from a string-like value.
§Errors
Returns an error if the input cannot be converted to a valid UTF-8 string.
Source§impl Scalar
impl Scalar
Sourcepub fn new(dtype: DType, value: ScalarValue) -> Self
pub fn new(dtype: DType, value: ScalarValue) -> Self
Creates a new scalar with the given data type and value.
Sourcepub fn value(&self) -> &ScalarValue
pub fn value(&self) -> &ScalarValue
Returns a reference to the scalar’s underlying value.
Sourcepub fn into_parts(self) -> (DType, ScalarValue)
pub fn into_parts(self) -> (DType, ScalarValue)
Consumes the scalar and returns its data type and value as a tuple.
Sourcepub fn into_value(self) -> ScalarValue
pub fn into_value(self) -> ScalarValue
Consumes the scalar and returns its underlying value.
Sourcepub fn null(dtype: DType) -> Self
pub fn null(dtype: DType) -> Self
Creates a null scalar with the given nullable data type.
§Panics
Panics if the data type is not nullable.
Sourcepub fn null_typed<T: ScalarType>() -> Self
pub fn null_typed<T: ScalarType>() -> Self
Creates a null scalar for the given scalar type.
The resulting scalar will have a nullable version of the type’s data type.
Sourcepub fn cast(&self, target: &DType) -> VortexResult<Self>
pub fn cast(&self, target: &DType) -> VortexResult<Self>
Casts the scalar to the target data type.
Returns an error if the cast is not supported or if the value cannot be represented in the target type.
Sourcepub fn into_nullable(self) -> Self
pub fn into_nullable(self) -> Self
Converts the scalar to have a nullable version of its data type.
Sourcepub fn default_value(dtype: DType) -> Self
pub fn default_value(dtype: DType) -> Self
Creates a “default” scalar value for the given data type.
For nullable types, returns null. For non-nullable types, returns an appropriate zero/empty value.
Source§impl Scalar
impl Scalar
Sourcepub fn as_bool(&self) -> BoolScalar<'_>
pub fn as_bool(&self) -> BoolScalar<'_>
Returns a view of the scalar as a boolean scalar.
§Panics
Panics if the scalar is not a boolean type.
Sourcepub fn as_bool_opt(&self) -> Option<BoolScalar<'_>>
pub fn as_bool_opt(&self) -> Option<BoolScalar<'_>>
Returns a view of the scalar as a boolean scalar if it has a boolean type.
Sourcepub fn as_primitive(&self) -> PrimitiveScalar<'_>
pub fn as_primitive(&self) -> PrimitiveScalar<'_>
Returns a view of the scalar as a primitive scalar.
§Panics
Panics if the scalar is not a primitive type.
Sourcepub fn as_primitive_opt(&self) -> Option<PrimitiveScalar<'_>>
pub fn as_primitive_opt(&self) -> Option<PrimitiveScalar<'_>>
Returns a view of the scalar as a primitive scalar if it has a primitive type.
Sourcepub fn as_decimal(&self) -> DecimalScalar<'_>
pub fn as_decimal(&self) -> DecimalScalar<'_>
Returns a view of the scalar as a decimal scalar.
§Panics
Panics if the scalar is not a decimal type.
Sourcepub fn as_decimal_opt(&self) -> Option<DecimalScalar<'_>>
pub fn as_decimal_opt(&self) -> Option<DecimalScalar<'_>>
Returns a view of the scalar as a decimal scalar if it has a decimal type.
Sourcepub fn as_utf8(&self) -> Utf8Scalar<'_>
pub fn as_utf8(&self) -> Utf8Scalar<'_>
Returns a view of the scalar as a UTF-8 string scalar.
§Panics
Panics if the scalar is not a UTF-8 type.
Sourcepub fn as_utf8_opt(&self) -> Option<Utf8Scalar<'_>>
pub fn as_utf8_opt(&self) -> Option<Utf8Scalar<'_>>
Returns a view of the scalar as a UTF-8 string scalar if it has a UTF-8 type.
Sourcepub fn as_binary(&self) -> BinaryScalar<'_>
pub fn as_binary(&self) -> BinaryScalar<'_>
Sourcepub fn as_binary_opt(&self) -> Option<BinaryScalar<'_>>
pub fn as_binary_opt(&self) -> Option<BinaryScalar<'_>>
Returns a view of the scalar as a binary scalar if it has a binary type.
Sourcepub fn as_struct(&self) -> StructScalar<'_>
pub fn as_struct(&self) -> StructScalar<'_>
Sourcepub fn as_struct_opt(&self) -> Option<StructScalar<'_>>
pub fn as_struct_opt(&self) -> Option<StructScalar<'_>>
Returns a view of the scalar as a struct scalar if it has a struct type.
Sourcepub fn as_list(&self) -> ListScalar<'_>
pub fn as_list(&self) -> ListScalar<'_>
Sourcepub fn as_list_opt(&self) -> Option<ListScalar<'_>>
pub fn as_list_opt(&self) -> Option<ListScalar<'_>>
Returns a view of the scalar as a list scalar if it has a list type.
Sourcepub fn as_extension(&self) -> ExtScalar<'_>
pub fn as_extension(&self) -> ExtScalar<'_>
Returns a view of the scalar as an extension scalar.
§Panics
Panics if the scalar is not an extension type.
Sourcepub fn as_extension_opt(&self) -> Option<ExtScalar<'_>>
pub fn as_extension_opt(&self) -> Option<ExtScalar<'_>>
Returns a view of the scalar as an extension scalar if it has an extension type.
Trait Implementations§
Source§impl From<Arc<Buffer<u8>>> for Scalar
impl From<Arc<Buffer<u8>>> for Scalar
Source§fn from(value: Arc<ByteBuffer>) -> Self
fn from(value: Arc<ByteBuffer>) -> Self
Source§impl From<Arc<BufferString>> for Scalar
impl From<Arc<BufferString>> for Scalar
Source§fn from(value: Arc<BufferString>) -> Self
fn from(value: Arc<BufferString>) -> Self
Source§impl From<Buffer<u8>> for Scalar
impl From<Buffer<u8>> for Scalar
Source§fn from(value: ByteBuffer) -> Self
fn from(value: ByteBuffer) -> Self
Source§impl From<BufferString> for Scalar
impl From<BufferString> for Scalar
Source§fn from(value: BufferString) -> Self
fn from(value: BufferString) -> Self
Source§impl From<DecimalScalar<'_>> for Scalar
impl From<DecimalScalar<'_>> for Scalar
Source§fn from(decimal_scalar: DecimalScalar<'_>) -> Self
fn from(decimal_scalar: DecimalScalar<'_>) -> Self
Source§impl From<DecimalValue> for Scalar
impl From<DecimalValue> for Scalar
Source§fn from(value: DecimalValue) -> Self
fn from(value: DecimalValue) -> Self
Source§impl From<PrimitiveScalar<'_>> for Scalar
impl From<PrimitiveScalar<'_>> for Scalar
Source§fn from(pscalar: PrimitiveScalar<'_>) -> Self
fn from(pscalar: PrimitiveScalar<'_>) -> Self
Source§impl From<Vec<Buffer<u8>>> for Scalar
impl From<Vec<Buffer<u8>>> for Scalar
Source§fn from(value: Vec<ByteBuffer>) -> Self
fn from(value: Vec<ByteBuffer>) -> Self
Source§impl From<Vec<BufferString>> for Scalar
impl From<Vec<BufferString>> for Scalar
Source§fn from(value: Vec<BufferString>) -> Self
fn from(value: Vec<BufferString>) -> Self
Source§impl From<usize> for Scalar
Read a scalar as usize. For usize only, we implicitly cast for better ergonomics.
impl From<usize> for Scalar
Read a scalar as usize. For usize only, we implicitly cast for better ergonomics.
Source§impl PartialOrd for Scalar
impl PartialOrd for Scalar
Source§fn partial_cmp(&self, other: &Self) -> Option<Ordering>
fn partial_cmp(&self, other: &Self) -> Option<Ordering>
Compares two scalar values for ordering.
§Returns
Some(Ordering)if both scalars have the same data type (ignoring nullability)Noneif the scalars have different data types
§Ordering Rules
When types match, the ordering follows these rules:
- Null values are considered less than all non-null values
- Non-null values are compared according to their natural ordering
§Examples
// Same types compare successfully
let a = Scalar::primitive(10i32, Nullability::NonNullable);
let b = Scalar::primitive(20i32, Nullability::NonNullable);
assert_eq!(a.partial_cmp(&b), Some(Ordering::Less));
// Different types return None
let int_scalar = Scalar::primitive(10i32, Nullability::NonNullable);
let str_scalar = Scalar::utf8("hello", Nullability::NonNullable);
assert_eq!(int_scalar.partial_cmp(&str_scalar), None);
// Nulls are less than non-nulls
let null = Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable));
let value = Scalar::primitive(0i32, Nullability::Nullable);
assert_eq!(null.partial_cmp(&value), Some(Ordering::Less));Source§impl<'a> TryFrom<&'a Scalar> for BinaryScalar<'a>
impl<'a> TryFrom<&'a Scalar> for BinaryScalar<'a>
Source§impl<'a> TryFrom<&'a Scalar> for BoolScalar<'a>
impl<'a> TryFrom<&'a Scalar> for BoolScalar<'a>
Source§impl<'a> TryFrom<&'a Scalar> for ByteBuffer
impl<'a> TryFrom<&'a Scalar> for ByteBuffer
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
Source§impl<'a> TryFrom<&'a Scalar> for BufferString
impl<'a> TryFrom<&'a Scalar> for BufferString
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
Source§impl<'a> TryFrom<&'a Scalar> for DecimalScalar<'a>
impl<'a> TryFrom<&'a Scalar> for DecimalScalar<'a>
Source§impl TryFrom<&Scalar> for DecimalValue
impl TryFrom<&Scalar> for DecimalValue
Source§impl<'a> TryFrom<&'a Scalar> for ListScalar<'a>
impl<'a> TryFrom<&'a Scalar> for ListScalar<'a>
Source§impl<'a> TryFrom<&'a Scalar> for Option<ByteBuffer>
impl<'a> TryFrom<&'a Scalar> for Option<ByteBuffer>
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
fn try_from(scalar: &'a Scalar) -> VortexResult<Self>
Source§impl TryFrom<&Scalar> for Option<bool>
impl TryFrom<&Scalar> for Option<bool>
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(value: &Scalar) -> VortexResult<Self>
fn try_from(value: &Scalar) -> VortexResult<Self>
Source§impl<'a> TryFrom<&'a Scalar> for PrimitiveScalar<'a>
impl<'a> TryFrom<&'a Scalar> for PrimitiveScalar<'a>
Source§impl<'a> TryFrom<&'a Scalar> for StructScalar<'a>
impl<'a> TryFrom<&'a Scalar> for StructScalar<'a>
Source§impl<'a> TryFrom<&'a Scalar> for Utf8Scalar<'a>
impl<'a> TryFrom<&'a Scalar> for Utf8Scalar<'a>
Source§impl TryFrom<&Scalar> for bool
impl TryFrom<&Scalar> for bool
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(value: &Scalar) -> VortexResult<Self>
fn try_from(value: &Scalar) -> VortexResult<Self>
Source§impl TryFrom<&Scalar> for usize
Read a scalar as usize. For usize only, we implicitly cast for better ergonomics.
impl TryFrom<&Scalar> for usize
Read a scalar as usize. For usize only, we implicitly cast for better ergonomics.
Source§impl TryFrom<Scalar> for ByteBuffer
impl TryFrom<Scalar> for ByteBuffer
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(scalar: Scalar) -> VortexResult<Self>
fn try_from(scalar: Scalar) -> VortexResult<Self>
Source§impl TryFrom<Scalar> for BufferString
impl TryFrom<Scalar> for BufferString
Source§impl TryFrom<Scalar> for DecimalValue
impl TryFrom<Scalar> for DecimalValue
Source§impl TryFrom<Scalar> for Option<ByteBuffer>
impl TryFrom<Scalar> for Option<ByteBuffer>
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(scalar: Scalar) -> VortexResult<Self>
fn try_from(scalar: Scalar) -> VortexResult<Self>
Source§impl TryFrom<Scalar> for Option<bool>
impl TryFrom<Scalar> for Option<bool>
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(value: Scalar) -> VortexResult<Self>
fn try_from(value: Scalar) -> VortexResult<Self>
Source§impl TryFrom<Scalar> for bool
impl TryFrom<Scalar> for bool
Source§type Error = VortexError
type Error = VortexError
Source§fn try_from(value: Scalar) -> VortexResult<Self>
fn try_from(value: Scalar) -> VortexResult<Self>
impl Eq for Scalar
Auto Trait Implementations§
impl Freeze for Scalar
impl RefUnwindSafe for Scalar
impl Send for Scalar
impl Sync for Scalar
impl Unpin for Scalar
impl UnwindSafe for Scalar
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more