mbrobbel commented on code in PR #5822: URL: https://github.com/apache/arrow-rs/pull/5822#discussion_r1925973798
########## arrow-schema/src/extension/mod.rs: ########## @@ -0,0 +1,252 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! Extension types. + +#[cfg(feature = "canonical_extension_types")] +mod canonical; +#[cfg(feature = "canonical_extension_types")] +pub use canonical::*; + +use crate::{ArrowError, DataType}; + +/// The metadata key for the string name identifying an [`ExtensionType`]. +pub const EXTENSION_TYPE_NAME_KEY: &str = "ARROW:extension:name"; + +/// The metadata key for a serialized representation of the [`ExtensionType`] +/// necessary to reconstruct the custom type. +pub const EXTENSION_TYPE_METADATA_KEY: &str = "ARROW:extension:metadata"; + +/// Extension types. +/// +/// User-defined “extension” types can be defined setting certain key value +/// pairs in the [`Field`] metadata structure. These extension keys are: +/// - [`EXTENSION_TYPE_NAME_KEY`] +/// - [`EXTENSION_TYPE_METADATA_KEY`] +/// +/// Canonical extension types support in this crate requires the +/// `canonical_extension_types` feature. +/// +/// Extension types may or may not use the [`EXTENSION_TYPE_METADATA_KEY`] +/// field. +/// +/// # Example +/// +/// The example below demonstrates how to implement this trait for a `Uuid` +/// type. Note this is not the canonical extension type for `Uuid`, which does +/// not include information about the `Uuid` version. +/// +/// ``` +/// # use arrow_schema::ArrowError; +/// # fn main() -> Result<(), ArrowError> { +/// use arrow_schema::{DataType, extension::ExtensionType, Field}; +/// use std::{fmt, str::FromStr}; +/// +/// /// The different Uuid versions. +/// #[derive(Clone, Copy, Debug, PartialEq)] +/// enum UuidVersion { +/// V1, +/// V2, +/// V3, +/// V4, +/// V5, +/// V6, +/// V7, +/// V8, +/// } +/// +/// // We'll use `Display` to serialize. +/// impl fmt::Display for UuidVersion { +/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { +/// write!( +/// f, +/// "{}", +/// match self { +/// Self::V1 => "V1", +/// Self::V2 => "V2", +/// Self::V3 => "V3", +/// Self::V4 => "V4", +/// Self::V5 => "V5", +/// Self::V6 => "V6", +/// Self::V7 => "V7", +/// Self::V8 => "V8", +/// } +/// ) +/// } +/// } +/// +/// // And `FromStr` to deserialize. +/// impl FromStr for UuidVersion { +/// type Err = ArrowError; +/// +/// fn from_str(s: &str) -> Result<Self, Self::Err> { +/// match s { +/// "V1" => Ok(Self::V1), +/// "V2" => Ok(Self::V2), +/// "V3" => Ok(Self::V3), +/// "V4" => Ok(Self::V4), +/// "V5" => Ok(Self::V5), +/// "V6" => Ok(Self::V6), +/// "V7" => Ok(Self::V7), +/// "V8" => Ok(Self::V8), +/// _ => Err(ArrowError::ParseError("Invalid UuidVersion".to_owned())), +/// } +/// } +/// } +/// +/// /// This is the extension type, not the container for Uuid values. It +/// /// stores the Uuid version (this is the metadata of this extension type). +/// #[derive(Clone, Copy, Debug, PartialEq)] +/// struct Uuid(UuidVersion); +/// +/// impl ExtensionType for Uuid { +/// // We use a namespace as suggested by the specification. +/// const NAME: &'static str = "myorg.example.uuid"; +/// +/// // The metadata type is the Uuid version. +/// type Metadata = UuidVersion; +/// +/// // We just return a reference to the Uuid version. +/// fn metadata(&self) -> &Self::Metadata { +/// &self.0 Review Comment: Yes, the current signature requires that. We could change it to return `Self::Metadata`? The pattern I used for the canonical extension types with metadata applied to your example: ```rust pub struct PointType(PointTypeMetadata); pub struct PointTypeMetadata(CoordType, Dimension); impl ExtensionType for PointType { const NAME: &'static str = "geoarrow.point"; type Metadata = PointTypeMetadata; fn metadata(&self) -> &Self::Metadata { &self.0 } } ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
