Struct Value 

pub struct Value { /* private fields */ }

An owned, RAII-managed DuckDB value.

When dropped, the underlying duckdb_value handle is destroyed via duckdb_destroy_value. This eliminates the manual duckdb_destroy_value calls that are easy to forget and lead to memory leaks.

Creation

Obtain a Value from:

• BindInfo::get_parameter_value
• BindInfo::get_named_parameter_value
• Value::from_raw (escape hatch for raw duckdb_value handles)

Extraction

Use typed accessors to extract the underlying data:

• as_str — VARCHAR → String
• as_i32 — INTEGER → i32
• as_i64 — BIGINT → i64
• as_f32 — FLOAT → f32
• as_f64 — DOUBLE → f64
• as_bool — BOOLEAN → bool

Implementations

impl Value

pub const unsafe fn from_raw(raw: duckdb_value) -> Self

Wraps a raw duckdb_value handle.

The returned Value takes ownership and will call duckdb_destroy_value on drop.

Safety

raw must be a valid duckdb_value obtained from a DuckDB API call (e.g., duckdb_bind_get_parameter). The caller must not destroy the value after passing it to this function.

pub fn as_str(&self) -> Result<String, ExtensionError>

Extracts the value as a String (VARCHAR).

Internally calls duckdb_get_varchar and frees the returned C string with duckdb_free. Returns an error if the string is not valid UTF-8 or if the value handle is null.

Errors

Returns ExtensionError if the value is null or contains invalid UTF-8.

pub fn as_i32(&self) -> i32

Extracts the value as an i32 (INTEGER).

DuckDB will attempt to cast the value to INTEGER. If the value is not numeric, this returns 0.

pub fn as_i64(&self) -> i64

Extracts the value as an i64 (BIGINT).

DuckDB will attempt to cast the value to BIGINT. If the value is not numeric, this returns 0.

pub fn as_f32(&self) -> f32

Extracts the value as an f32 (FLOAT).

DuckDB will attempt to cast the value to FLOAT. If the value is not numeric, this returns 0.0.

pub fn as_f64(&self) -> f64

Extracts the value as an f64 (DOUBLE).

DuckDB will attempt to cast the value to DOUBLE. If the value is not numeric, this returns 0.0.

pub fn as_bool(&self) -> bool

Extracts the value as a bool (BOOLEAN).

DuckDB will attempt to cast the value to BOOLEAN. If the value is not convertible, this returns false.

pub fn as_i8(&self) -> i8

Extracts the value as an i8 (TINYINT).

DuckDB will attempt to cast the value to TINYINT. If the value is not numeric, this returns 0.

pub fn as_i16(&self) -> i16

Extracts the value as an i16 (SMALLINT).

DuckDB will attempt to cast the value to SMALLINT. If the value is not numeric, this returns 0.

pub fn as_u8(&self) -> u8

Extracts the value as a u8 (UTINYINT).

DuckDB will attempt to cast the value to UTINYINT. If the value is not numeric, this returns 0.

pub fn as_u16(&self) -> u16

Extracts the value as a u16 (USMALLINT).

DuckDB will attempt to cast the value to USMALLINT. If the value is not numeric, this returns 0.

pub fn as_u32(&self) -> u32

Extracts the value as a u32 (UINTEGER).

DuckDB will attempt to cast the value to UINTEGER. If the value is not numeric, this returns 0.

pub fn as_u64(&self) -> u64

Extracts the value as a u64 (UBIGINT).

DuckDB will attempt to cast the value to UBIGINT. If the value is not numeric, this returns 0.

pub fn as_i128(&self) -> i128

Extracts the value as an i128 (HUGEINT).

DuckDB returns HUGEINT as { lower: u64, upper: i64 }. This method reconstructs the full i128 value.

pub fn as_str_or(&self, default: &str) -> String

Extracts the value as a String, returning default on failure.

Convenience for val.as_str().unwrap_or_else(|_| default.to_owned()).

pub fn as_str_or_default(&self) -> String

Extracts the value as a String, returning an empty string on failure.

Convenience for val.as_str().unwrap_or_default().

pub fn as_i32_or(&self, default: i32) -> i32

Extracts the value as an i32, returning default if the handle is null.

pub fn as_i64_or(&self, default: i64) -> i64

Extracts the value as an i64, returning default if the handle is null.

pub fn as_f32_or(&self, default: f32) -> f32

Extracts the value as an f32, returning default if the handle is null.

pub fn as_f64_or(&self, default: f64) -> f64

Extracts the value as an f64, returning default if the handle is null.

pub fn as_bool_or(&self, default: bool) -> bool

Extracts the value as a bool, returning default if the handle is null.

pub fn as_i8_or(&self, default: i8) -> i8

Extracts the value as an i8, returning default if the handle is null.

pub fn as_i16_or(&self, default: i16) -> i16

Extracts the value as an i16, returning default if the handle is null.

pub fn as_u8_or(&self, default: u8) -> u8

Extracts the value as a u8, returning default if the handle is null.

pub fn as_u16_or(&self, default: u16) -> u16

Extracts the value as a u16, returning default if the handle is null.

pub fn as_u32_or(&self, default: u32) -> u32

Extracts the value as a u32, returning default if the handle is null.

pub fn as_u64_or(&self, default: u64) -> u64

Extracts the value as a u64, returning default if the handle is null.

pub fn as_i128_or(&self, default: i128) -> i128

Extracts the value as an i128, returning default if the handle is null.

pub fn time_ns(nanos: i64) -> Self

Creates a TIME_NS value (time of day with nanosecond precision) from a raw nanosecond count (DuckDB 1.5.0+).

Pairs with as_time_ns and the TypeId::TimeNs column type.

pub fn as_time_ns(&self) -> i64

Extracts the value as a TIME_NS nanosecond count (DuckDB 1.5.0+).

Returns 0 if the value is not a TIME_NS.

pub fn display_string(&self) -> Option<String>

Returns the canonical string representation of this value, as DuckDB would render it (DuckDB 1.5.0+).

Returns None if the handle is null or the rendered text is not valid UTF-8. This is primarily useful for diagnostics and error messages, where it works for any value type (not just VARCHAR).

pub const fn is_null(&self) -> bool

Returns true if the underlying handle is null.

pub const fn as_raw(&self) -> duckdb_value

Returns the raw duckdb_value handle without consuming the Value.

The Value still owns the handle and will destroy it on drop.

pub const fn into_raw(self) -> duckdb_value

Consumes the Value and returns the raw duckdb_value handle.

The caller takes ownership and is responsible for calling duckdb_destroy_value when done.

Trait Implementations

impl Drop for Value

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.