Implementation:Pola rs Polars CatNative
| Knowledge Sources | |
|---|---|
| Domains | Type_System, Categorical_Data |
| Last Updated | 2026-02-09 09:00 GMT |
Overview
Concrete tool for defining the type alias and conversion trait for categorical index types provided by the polars-dtype crate.
Description
This module defines CatSize as a type alias for u32, which is the canonical representation for categorical indices in Polars. The CatNative trait provides bidirectional conversion between the physical storage types (u8, u16, u32) and the canonical CatSize type. The trait has two methods: as_cat (convert from native to CatSize) and from_cat (convert from CatSize to native). The implementations for u8 and u16 use checked conversion in debug mode (via try_into().unwrap()) and unchecked truncation in release mode for performance, while the u32 implementation is a no-op identity conversion.
Usage
Import CatSize and CatNative when implementing categorical array operations that need to work generically across different physical backing types. This is primarily used internally by the categorical encoding and decoding paths.
Code Reference
Source Location
- Repository: Pola_rs_Polars
- File: crates/polars-dtype/src/categorical/catsize.rs
- Lines: 1-52
Signature
pub type CatSize = u32;
pub trait CatNative {
fn as_cat(&self) -> CatSize;
fn from_cat(cat: CatSize) -> Self;
}
impl CatNative for u8 { ... }
impl CatNative for u16 { ... }
impl CatNative for u32 { ... }
Import
use polars_dtype::categorical::{CatSize, CatNative};
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| self (as_cat) | u8, u16, or u32 | Yes | Native physical value to convert to canonical CatSize |
| cat (from_cat) | CatSize (u32) | Yes | Canonical categorical index to convert to native type |
Outputs
| Name | Type | Description |
|---|---|---|
| as_cat returns | CatSize (u32) | Widened categorical index |
| from_cat returns | Self (u8/u16/u32) | Narrowed native value (debug-checked for overflow) |
Usage Examples
Converting Between Physical Types
use polars_dtype::categorical::{CatSize, CatNative};
// u8 to CatSize
let val: u8 = 42;
let cat: CatSize = val.as_cat();
assert_eq!(cat, 42u32);
// CatSize back to u8
let native: u8 = CatNative::from_cat(42);
assert_eq!(native, 42u8);
// u32 is identity
let val: u32 = 1000;
let cat: CatSize = val.as_cat();
assert_eq!(cat, 1000u32);