Struct UnionFields

pub struct UnionFields(Arc<[(i8, Arc<Field>)]>);

Expand description

A cheaply cloneable, owned collection of FieldRef and their corresponding type ids

Tuple Fields§

§0: Arc<[(i8, Arc<Field>)]>

Implementations§

§

impl UnionFields

pub fn empty() -> UnionFields

Create a new UnionFields with no fields

pub fn try_new<F, T>(type_ids: T, fields: F) -> Result<UnionFields, ArrowError>
where F: IntoIterator, <F as IntoIterator>::Item: Into<Arc<Field>>, T: IntoIterator<Item = i8>,

Create a new UnionFields from a Fields and array of type_ids

See https://arrow.apache.org/docs/format/Columnar.html#union-layout

§Errors

This function returns an error if:

Any type_id appears more than once (duplicate type ids)
The type_ids are duplicated

§Examples

use arrow_schema::{DataType, Field, UnionFields};
// Create a new UnionFields with type id mapping
// 1 -> DataType::UInt8
// 3 -> DataType::Utf8
let result = UnionFields::try_new(
    vec![1, 3],
    vec![
        Field::new("field1", DataType::UInt8, false),
        Field::new("field3", DataType::Utf8, false),
    ],
);
assert!(result.is_ok());

// This will fail due to duplicate type ids
let result = UnionFields::try_new(
    vec![1, 1],
    vec![
        Field::new("field1", DataType::UInt8, false),
        Field::new("field2", DataType::Utf8, false),
    ],
);
assert!(result.is_err());

pub fn from_fields<F>(fields: F) -> UnionFields
where F: IntoIterator, <F as IntoIterator>::Item: Into<Arc<Field>>,

Create a new UnionFields from a collection of fields with automatically assigned type IDs starting from 0.

The type IDs are assigned in increasing order: 0, 1, 2, 3, etc.

See https://arrow.apache.org/docs/format/Columnar.html#union-layout

§Panics

Panics if the number of fields exceeds 127 (the maximum value for i8 type IDs).

If you want to avoid panics, use UnionFields::try_from_fields instead, which returns a Result.

§Examples

use arrow_schema::{DataType, Field, UnionFields};
// Create a new UnionFields with automatic type id assignment
// 0 -> DataType::UInt8
// 1 -> DataType::Utf8
let union_fields = UnionFields::from_fields(vec![
    Field::new("field1", DataType::UInt8, false),
    Field::new("field2", DataType::Utf8, false),
]);
assert_eq!(union_fields.len(), 2);

pub fn try_from_fields<F>(fields: F) -> Result<UnionFields, ArrowError>
where F: IntoIterator, <F as IntoIterator>::Item: Into<Arc<Field>>,

Create a new UnionFields from a collection of fields with automatically assigned type IDs starting from 0.

The type IDs are assigned in increasing order: 0, 1, 2, 3, etc.

This is the non-panicking version of UnionFields::from_fields.

See https://arrow.apache.org/docs/format/Columnar.html#union-layout

§Errors

Returns an error if the number of fields exceeds 127 (the maximum value for i8 type IDs).

§Examples

use arrow_schema::{DataType, Field, UnionFields};
// Create a new UnionFields with automatic type id assignment
// 0 -> DataType::UInt8
// 1 -> DataType::Utf8
let result = UnionFields::try_from_fields(vec![
    Field::new("field1", DataType::UInt8, false),
    Field::new("field2", DataType::Utf8, false),
]);
assert!(result.is_ok());
assert_eq!(result.unwrap().len(), 2);

// This will fail with too many fields
let many_fields: Vec<_> = (0..200)
    .map(|i| Field::new(format!("field{}", i), DataType::Int32, false))
    .collect();
let result = UnionFields::try_from_fields(many_fields);
assert!(result.is_err());

pub fn new<F, T>(type_ids: T, fields: F) -> UnionFields
where F: IntoIterator, <F as IntoIterator>::Item: Into<Arc<Field>>, T: IntoIterator<Item = i8>,

👎Deprecated since 57.0.0: Use try_new instead

Create a new UnionFields from a Fields and array of type_ids

See https://arrow.apache.org/docs/format/Columnar.html#union-layout

§Deprecated

Use UnionFields::try_new instead. This method panics on invalid input, while try_new returns a Result.

§Panics

Panics if any type_id appears more than once (duplicate type ids).

use arrow_schema::{DataType, Field, UnionFields};
// Create a new UnionFields with type id mapping
// 1 -> DataType::UInt8
// 3 -> DataType::Utf8
UnionFields::try_new(
    vec![1, 3],
    vec![
        Field::new("field1", DataType::UInt8, false),
        Field::new("field3", DataType::Utf8, false),
    ],
);

pub fn size(&self) -> usize

Return size of this instance in bytes.

pub fn len(&self) -> usize

Returns the number of fields in this UnionFields

pub fn is_empty(&self) -> bool

Returns true if this is empty

pub fn iter(&self) -> impl Iterator<Item = (i8, &Arc<Field>)>

Returns an iterator over the fields and type ids in this UnionFields

pub fn get(&self, index: usize) -> Option<&(i8, Arc<Field>)>

Returns a reference to the field at the given index, or None if out of bounds.

This is a safe alternative to direct indexing via [].

§Example

use arrow_schema::{DataType, Field, UnionFields};

let fields = UnionFields::new(
    vec![1, 3],
    vec![
        Field::new("field1", DataType::UInt8, false),
        Field::new("field3", DataType::Utf8, false),
    ],
);

assert!(fields.get(0).is_some());
assert!(fields.get(1).is_some());
assert!(fields.get(2).is_none());

pub fn find_by_type_id(&self, type_id: i8) -> Option<(i8, &Arc<Field>)>

Searches for a field by its type id, returning the type id and field reference if found. Returns None if no field with the given type id exists.

pub fn find_by_field(&self, field: &Field) -> Option<(i8, &Arc<Field>)>

Searches for a field by value equality, returning its type id and reference if found. Returns None if no matching field exists in this UnionFields.