Class: DuckDB::Value

Inherits:
Object
  • Object
show all
Extended by:
Converter
Defined in:
lib/duckdb/value.rb,
ext/duckdb/value.c

Constant Summary

Constants included from Converter

Converter::EPOCH, Converter::EPOCH_UTC, Converter::HALF_HUGEINT, Converter::HALF_HUGEINT_BIT, Converter::LOWER_HUGEINT_MASK, Converter::RANGE_DECIMAL_WIDTH, Converter::RANGE_HUGEINT, Converter::RANGE_INT16, Converter::RANGE_INT32, Converter::RANGE_INT64, Converter::RANGE_INT8, Converter::RANGE_UHUGEINT, Converter::RANGE_UINT16, Converter::RANGE_UINT32, Converter::RANGE_UINT64, Converter::RANGE_UINT8

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Converter

_decimal_to_unscaled, _decimal_width, _hugeint_lower, _hugeint_upper, _parse_date, _parse_deciaml, _parse_time, _to_date, _to_decimal_from_hugeint, _to_decimal_from_value, _to_hugeint_from_vector, _to_infinity, _to_interval_from_vector, _to_query_progress, _to_time, _to_time_from_duckdb_time, _to_time_from_duckdb_time_ns, _to_time_from_duckdb_time_tz, _to_time_from_duckdb_timestamp_ms, _to_time_from_duckdb_timestamp_ns, _to_time_from_duckdb_timestamp_s, _to_time_from_duckdb_timestamp_tz, decimal_to_hugeint, default_timezone_utc?, format_timestamp_with_micro, format_timezone_offset, integer_to_hugeint

Class Method Details

.create_array(child_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of ARRAY type. The array size is the number of elements given. The first argument is the element type: a Symbol (e.g. :integer) or a DuckDB::LogicalType. The second argument is an Array of DuckDB::Value elements.

values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
array = DuckDB::Value.create_array(:integer, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if child_type cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if values is not an Array of DuckDB::Value.



522
523
524
525
526
 
# File 'lib/duckdb/value.rb', line 522

def create_array(child_type, values)
  check_value_array!(values)

  _create_array(DuckDB::LogicalType.resolve(child_type), values)
end

.create_bignum(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BIGNUM (arbitrary-precision integer) type.

value = DuckDB::Value.create_bignum(2**200)

Parameters:

  • value (Integer) —

    the integer value, of arbitrary size.

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer.



479
480
481
482
483
484
485
 
# File 'lib/duckdb/value.rb', line 479

def create_bignum(value)
  check_type!(value, Integer)

  hex = value.abs.to_s(16)
  hex = "0#{hex}" if hex.length.odd?
  _create_bignum([hex].pack('H*'), value.negative?)
end

.create_bit(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BIT (bitstring) type.

value = DuckDB::Value.create_bit('0101')

Parameters:

  • value (String) —

    the bitstring: '0'/'1' characters, MSB first.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a non-empty String of '0' and '1' characters.



463
464
465
466
467
468
469
 
# File 'lib/duckdb/value.rb', line 463

def create_bit(value)
  check_type!(value, String)
  raise ArgumentError, "expected a String of '0'/'1' characters" unless value.match?(/\A[01]+\z/)

  pad = -value.length % 8
  _create_bit("#{pad.chr}#{[('1' * pad) + value].pack('B*')}".b)
end

.create_blob(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of BLOB type.

value = DuckDB::Value.create_blob("\x00\x01\x02".b)

Parameters:

  • value (String) —

    the binary string value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a BINARY encoded String.



188
189
190
191
192
 
# File 'lib/duckdb/value.rb', line 188

def create_blob(value)
  check_type!(value, String)
  check_binary!(value)
  _create_blob(value)
end

.create_bool(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a boolean value.

require 'duckdb'
value = DuckDB::Value.create_bool(true)

Parameters:

  • value (TrueClass, FalseClass) —

    the boolean value

Returns:

Raises:

  • (ArgumentError) —

    if value is not a boolean



18
19
20
21
22
 
# File 'lib/duckdb/value.rb', line 18

def create_bool(value)
  check_type!(value, [TrueClass, FalseClass])

  _create_bool(value)
end

.create_date(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DATE type. The argument is parsed leniently: a Date, a Time, or a String accepted by Date.parse, matching Appender#append_date.

value = DuckDB::Value.create_date(Date.new(2026, 7, 12))
value = DuckDB::Value.create_date('2026-07-12')

Parameters:

  • value (Date, Time, String) —

    the date value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Date.



251
252
253
254
 
# File 'lib/duckdb/value.rb', line 251

def create_date(value)
  date = _parse_date(value)
  _create_date(date.year, date.month, date.day)
end

.create_decimal(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DECIMAL type.

value = DuckDB::Value.create_decimal(BigDecimal('12345.678'))

Parameters:

  • value (BigDecimal) —

    the decimal value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a BigDecimal or its width is out of range (1..38).



231
232
233
234
235
236
237
238
239
 
# File 'lib/duckdb/value.rb', line 231

def create_decimal(value)
  check_type!(value, BigDecimal)

  width = _decimal_width(value)
  check_range!(width, RANGE_DECIMAL_WIDTH, 'DECIMAL width')

  lower, upper = decimal_to_hugeint(value)
  _create_decimal(lower, upper, width, value.scale)
end

.create_double(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of DOUBLE type.

value = DuckDB::Value.create_double(1.5)

Parameters:

  • value (Numeric) —

    the numeric value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a Numeric.



163
164
165
166
 
# File 'lib/duckdb/value.rb', line 163

def create_double(value)
  check_type!(value, [Integer, Float])
  _create_double(value)
end

.create_enum(enum_type, member) ⇒ DuckDB::Value

Creates a DuckDB::Value of ENUM type. The first argument is the enum type: an Array of member names (as accepted by DuckDB::LogicalType.create_enum) or an ENUM DuckDB::LogicalType. The second argument is the member: its name (String or Symbol) or its 0-based index (Integer).

value = DuckDB::Value.create_enum(%w[happy sad neutral], 'sad')

# equivalent, with an explicit ENUM logical type:
enum_type = DuckDB::LogicalType.create_enum('happy', 'sad', 'neutral')
value = DuckDB::Value.create_enum(enum_type, 'sad')

Parameters:

  • enum_type (Array<String>, DuckDB::LogicalType) —

    the member names or ENUM logical type.

  • member (String, Symbol, Integer) —

    the member name or 0-based index.

Returns:

Raises:

  • (ArgumentError) —

    if enum_type is not an Array or an ENUM DuckDB::LogicalType, or member is not a member of the enum.



412
413
414
415
416
417
418
 
# File 'lib/duckdb/value.rb', line 412

def create_enum(enum_type, member)
  enum_type = DuckDB::LogicalType.create_enum(*enum_type) if enum_type.is_a?(Array)
  check_type!(enum_type, DuckDB::LogicalType)
  raise ArgumentError, "expected ENUM LogicalType, got #{enum_type.type}" unless enum_type.type == :enum

  _create_enum(enum_type, enum_member_index(enum_type, member))
end

.create_float(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of FLOAT type.

value = DuckDB::Value.create_float(1.5)

Parameters:

  • value (Numeric) —

    the numeric value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a Numeric.



151
152
153
154
 
# File 'lib/duckdb/value.rb', line 151

def create_float(value)
  check_type!(value, [Integer, Float])
  _create_float(value)
end

.create_hugeint(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of HUGEINT type.

value = DuckDB::Value.create_hugeint(1_234_567_890_123_456_789_012_345)

Parameters:

  • value (Integer) —

    the integer value (-(2127)..(2127 - 1))

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range.



201
202
203
204
205
206
207
 
# File 'lib/duckdb/value.rb', line 201

def create_hugeint(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_HUGEINT, 'HUGEINT')

  lower, upper = integer_to_hugeint(value)
  _create_hugeint(lower, upper)
end

.create_int16(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT16 (SMALLINT) value.

require 'duckdb'
value = DuckDB::Value.create_int16(32_767)

Parameters:

  • value (Integer) —

    the integer value (-32768..32767)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



47
48
49
50
51
52
 
# File 'lib/duckdb/value.rb', line 47

def create_int16(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT16, 'INT16')

  _create_int16(value)
end

.create_int32(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT32 (INTEGER) value.

require 'duckdb'
value = DuckDB::Value.create_int32(2_147_483_647)

Parameters:

  • value (Integer) —

    the integer value (-2147483648..2147483647)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



62
63
64
65
66
67
 
# File 'lib/duckdb/value.rb', line 62

def create_int32(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT32, 'INT32')

  _create_int32(value)
end

.create_int64(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT64 (BIGINT) value.

require 'duckdb'
value = DuckDB::Value.create_int64(9_223_372_036_854_775_807)

Parameters:

  • value (Integer) —

    the integer value (-9223372036854775808..9223372036854775807)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



77
78
79
80
81
82
 
# File 'lib/duckdb/value.rb', line 77

def create_int64(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT64, 'INT64')

  _create_int64(value)
end

.create_int8(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with an INT8 (TINYINT) value.

require 'duckdb'
value = DuckDB::Value.create_int8(127)

Parameters:

  • value (Integer) —

    the integer value (-128..127)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



32
33
34
35
36
37
 
# File 'lib/duckdb/value.rb', line 32

def create_int8(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_INT8, 'INT8')

  _create_int8(value)
end

.create_interval(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of INTERVAL type. Unlike the other temporal creators, the input is strict: it must be a DuckDB::Interval.

interval = DuckDB::Interval.new(interval_months: 14, interval_days: 3, interval_micros: 12_000_000)
value = DuckDB::Value.create_interval(interval)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if value is not a DuckDB::Interval.



388
389
390
391
392
 
# File 'lib/duckdb/value.rb', line 388

def create_interval(value)
  check_type!(value, DuckDB::Interval)

  _create_interval(value.interval_months, value.interval_days, value.interval_micros)
end

.create_list(child_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of LIST type. The first argument is the element type: a Symbol (e.g. :integer) or a DuckDB::LogicalType. The second argument is an Array of DuckDB::Value elements.

values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
list = DuckDB::Value.create_list(:integer, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if child_type cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if values is not an Array of DuckDB::Value.



501
502
503
504
505
 
# File 'lib/duckdb/value.rb', line 501

def create_list(child_type, values)
  check_value_array!(values)

  _create_list(DuckDB::LogicalType.resolve(child_type), values)
end

.create_map(map_type, entries) ⇒ DuckDB::Value

Creates a DuckDB::Value of MAP type. The first argument is the type spec: a one-pair Hash of key type to value type (each a Symbol or a DuckDB::LogicalType, as accepted by DuckDB::LogicalType.create_map) or a MAP DuckDB::LogicalType. The second argument is a Hash of DuckDB::Value keys to DuckDB::Value values.

entries = {
DuckDB::Value.create_varchar('a') => DuckDB::Value.create_int32(1),
DuckDB::Value.create_varchar('b') => DuckDB::Value.create_int32(2)
}
map = DuckDB::Value.create_map({ varchar: :integer }, entries)

# equivalent, with an explicit MAP logical type:
map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
map = DuckDB::Value.create_map(map_type, entries)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if a type in the Hash spec cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if map_type is not a one-pair Hash or a MAP DuckDB::LogicalType, or entries is not a Hash of DuckDB::Value to DuckDB::Value.



590
591
592
593
594
595
596
597
 
# File 'lib/duckdb/value.rb', line 590

def create_map(map_type, entries)
  map_type = resolve_map_type(map_type)
  check_type!(entries, Hash)
  check_value_array!(entries.keys)
  check_value_array!(entries.values)

  _create_map(map_type, entries.keys, entries.values)
end

.create_null ⇒ Object 



309
310
311
312
 
# File 'ext/duckdb/value.c', line 309

static VALUE value_s_create_null(VALUE klass) {
    duckdb_value value = duckdb_create_null_value();
    return rbduckdb_value_new(value);
}

.create_struct(struct_type, values) ⇒ DuckDB::Value

Creates a DuckDB::Value of STRUCT type. The first argument is the field spec: a Hash of field name to field type (a Symbol or a DuckDB::LogicalType, as accepted by DuckDB::LogicalType.create_struct) or a STRUCT DuckDB::LogicalType. The second argument is an Array of DuckDB::Value field values, positional, matching the struct's field order.

values = [DuckDB::Value.create_int32(1), DuckDB::Value.create_varchar('x')]
struct = DuckDB::Value.create_struct({ a: :integer, b: :varchar }, values)

# equivalent, with an explicit STRUCT logical type:
struct_type = DuckDB::LogicalType.create_struct(a: :integer, b: :varchar)
struct = DuckDB::Value.create_struct(struct_type, values)

Parameters:

Returns:

Raises:

  • (DuckDB::Error) —

    if a field type in the Hash cannot be resolved to a DuckDB::LogicalType.

  • (ArgumentError) —

    if struct_type is not a Hash or a STRUCT DuckDB::LogicalType, values is not an Array of DuckDB::Value, or values.size does not match the struct's field count.



550
551
552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'lib/duckdb/value.rb', line 550

def create_struct(struct_type, values)
  struct_type = DuckDB::LogicalType.create_struct(**struct_type) if struct_type.is_a?(Hash)
  check_type!(struct_type, DuckDB::LogicalType)
  raise ArgumentError, "expected STRUCT LogicalType, got #{struct_type.type}" unless struct_type.type == :struct

  check_value_array!(values)
  # The C API's duckdb_create_struct_value reads exactly child_count
  # values from the buffer with no count argument, so a size mismatch
  # here would cause an out-of-bounds read in C.
  n = struct_type.child_count
  raise ArgumentError, "expected #{n} values for STRUCT, got #{values.size}" unless values.size == n

  _create_struct(struct_type, values)
end

.create_time(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIME type (microsecond precision). The argument is parsed leniently: a Time or a String accepted by Time.parse, matching Appender#append_time.

value = DuckDB::Value.create_time(Time.now)
value = DuckDB::Value.create_time('12:34:56.789')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



266
267
268
269
 
# File 'lib/duckdb/value.rb', line 266

def create_time(value)
  time = _parse_time(value)
  _create_time(time.hour, time.min, time.sec, time.usec)
end

.create_time_ns(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIME_NS type (nanosecond precision). The argument is parsed leniently: a Time or a String accepted by Time.parse. Nanoseconds are preserved.

value = DuckDB::Value.create_time_ns(Time.now)
value = DuckDB::Value.create_time_ns('12:34:56.123456789')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



281
282
283
284
 
# File 'lib/duckdb/value.rb', line 281

def create_time_ns(value)
  time = _parse_time(value)
  _create_time_ns(time.hour, time.min, time.sec, time.nsec)
end

.create_time_tz(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMETZ type (time with UTC offset). The argument is parsed leniently: a Time (the offset is taken from the Time) or a String accepted by Time.parse.

value = DuckDB::Value.create_time_tz(Time.now)
value = DuckDB::Value.create_time_tz('12:34:56.789012+05:30')

Parameters:

  • value (Time, String) —

    the time value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



296
297
298
299
300
 
# File 'lib/duckdb/value.rb', line 296

def create_time_tz(value)
  time = _parse_time(value)
  micros = (((((time.hour * 60) + time.min) * 60) + time.sec) * 1_000_000) + time.usec
  _create_time_tz(micros, time.utc_offset)
end

.create_timestamp(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP type (microsecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse, matching Appender#append_timestamp.

value = DuckDB::Value.create_timestamp(Time.now)
value = DuckDB::Value.create_timestamp('2026-07-12 12:34:56.789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



312
313
314
315
 
# File 'lib/duckdb/value.rb', line 312

def create_timestamp(value)
  time = to_time(value)
  _create_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
end

.create_timestamp_ms(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_MS type (millisecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Sub-millisecond input is truncated.

value = DuckDB::Value.create_timestamp_ms(Time.now)
value = DuckDB::Value.create_timestamp_ms('2026-07-12 12:34:56.789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



342
343
344
345
 
# File 'lib/duckdb/value.rb', line 342

def create_timestamp_ms(value)
  time = to_time(value)
  _create_timestamp_ms(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
end

.create_timestamp_ns(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_NS type (nanosecond precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Nanoseconds are preserved.

value = DuckDB::Value.create_timestamp_ns(Time.now)
value = DuckDB::Value.create_timestamp_ns('2026-07-12 12:34:56.123456789')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



357
358
359
360
 
# File 'lib/duckdb/value.rb', line 357

def create_timestamp_ns(value)
  time = to_time(value)
  _create_timestamp_ns(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec)
end

.create_timestamp_s(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP_S type (second precision). The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. Sub-second input is truncated to seconds.

value = DuckDB::Value.create_timestamp_s(Time.now)
value = DuckDB::Value.create_timestamp_s('2026-07-12 12:34:56')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



327
328
329
330
 
# File 'lib/duckdb/value.rb', line 327

def create_timestamp_s(value)
  time = to_time(value)
  _create_timestamp_s(time.year, time.month, time.day, time.hour, time.min, time.sec)
end

.create_timestamp_tz(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of TIMESTAMP WITH TIME ZONE type. The argument is parsed leniently: a Time, a Date, or a String accepted by Time.parse. The instant is stored (as microseconds since the Unix epoch), so the input's UTC offset is honored.

value = DuckDB::Value.create_timestamp_tz(Time.now)
value = DuckDB::Value.create_timestamp_tz('2026-07-12 12:34:56.789+05:30')

Parameters:

  • value (Time, Date, String) —

    the timestamp value.

Returns:

Raises:

  • (ArgumentError) —

    if value cannot be parsed to a Time.



373
374
375
376
 
# File 'lib/duckdb/value.rb', line 373

def create_timestamp_tz(value)
  time = to_time(value)
  _create_timestamp_tz((time.to_i * 1_000_000) + time.usec)
end

.create_uhugeint(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of UHUGEINT type.

value = DuckDB::Value.create_uhugeint(340_282_366_920_938_463_463_374_607_431_768_211_455)

Parameters:

  • value (Integer) —

    the integer value (0..(2**128 - 1))

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range.



216
217
218
219
220
221
222
 
# File 'lib/duckdb/value.rb', line 216

def create_uhugeint(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UHUGEINT, 'UHUGEINT')

  lower, upper = integer_to_hugeint(value)
  _create_uhugeint(lower, upper)
end

.create_uint16(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT16 (USMALLINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint16(65_535)

Parameters:

  • value (Integer) —

    the integer value (0..65535)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



107
108
109
110
111
112
 
# File 'lib/duckdb/value.rb', line 107

def create_uint16(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT16, 'UINT16')

  _create_uint16(value)
end

.create_uint32(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT32 (UINTEGER) value.

require 'duckdb'
value = DuckDB::Value.create_uint32(4_294_967_295)

Parameters:

  • value (Integer) —

    the integer value (0..4294967295)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



122
123
124
125
126
127
 
# File 'lib/duckdb/value.rb', line 122

def create_uint32(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT32, 'UINT32')

  _create_uint32(value)
end

.create_uint64(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT64 (UBIGINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint64(18_446_744_073_709_551_615)

Parameters:

  • value (Integer) —

    the integer value (0..18446744073709551615)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



137
138
139
140
141
142
 
# File 'lib/duckdb/value.rb', line 137

def create_uint64(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT64, 'UINT64')

  _create_uint64(value)
end

.create_uint8(value) ⇒ DuckDB::Value

Creates a new DuckDB::Value with a UINT8 (UTINYINT) value.

require 'duckdb'
value = DuckDB::Value.create_uint8(255)

Parameters:

  • value (Integer) —

    the integer value (0..255)

Returns:

Raises:

  • (ArgumentError) —

    if value is not an Integer or out of range



92
93
94
95
96
97
 
# File 'lib/duckdb/value.rb', line 92

def create_uint8(value)
  check_type!(value, Integer)
  check_range!(value, RANGE_UINT8, 'UINT8')

  _create_uint8(value)
end

.create_union(union_type, tag, member_value) ⇒ DuckDB::Value

Creates a DuckDB::Value of UNION type. The first argument is the union type: a Hash of member name to member type (as accepted by DuckDB::LogicalType.create_union) or a UNION DuckDB::LogicalType. The second argument is the member tag (String or Symbol), and the third is the member value as a DuckDB::Value of the tagged type.

value = DuckDB::Value.create_union({ num: :integer, str: :varchar }, :num, DuckDB::Value.create_int32(42))
value.to_ruby #=> 42

# equivalent, with an explicit UNION logical type:
union_type = DuckDB::LogicalType.create_union(num: :integer, str: :varchar)
value = DuckDB::Value.create_union(union_type, :num, DuckDB::Value.create_int32(42))

Parameters:

  • union_type (Hash, DuckDB::LogicalType) —

    the member spec or UNION logical type.

  • tag (String, Symbol) —

    the member tag.

  • member_value (DuckDB::Value) —

    the member value.

Returns:

Raises:

  • (ArgumentError) —

    if union_type is not a Hash or a UNION DuckDB::LogicalType, tag is not a member of the union, or member_value is not a DuckDB::Value.

  • (DuckDB::Error) —

    if member_value does not match the tagged member's type.



443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/duckdb/value.rb', line 443

def create_union(union_type, tag, member_value)
  union_type = DuckDB::LogicalType.create_union(**union_type) if union_type.is_a?(Hash)
  check_type!(union_type, DuckDB::LogicalType)
  raise ArgumentError, "expected UNION LogicalType, got #{union_type.type}" unless union_type.type == :union

  check_type!(member_value, DuckDB::Value)
  tag_index = union_type.each_member_name.find_index(tag.to_s)
  raise ArgumentError, "`#{tag}` is not a member of the union" if tag_index.nil?

  _create_union(union_type, tag_index, member_value)
end

.create_varchar(value) ⇒ DuckDB::Value

Creates a DuckDB::Value of VARCHAR type.

value = DuckDB::Value.create_varchar('hello')

Parameters:

  • value (String) —

    the string value.

Returns:

Raises:

  • (ArgumentError) —

    if value is not a String.



175
176
177
178
179
 
# File 'lib/duckdb/value.rb', line 175

def create_varchar(value)
  check_type!(value, String)
  check_utf8_compatible!(value)
  _create_varchar(value)
end

Instance Method Details

#list_child(vidx) ⇒ Object 



442
443
444
445
446
447
448
449
 
# File 'ext/duckdb/value.c', line 442

static VALUE value_list_child(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_list_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "list index out of range (or the value is not a LIST)");
    }
    return rbduckdb_value_new(child);
}

#list_size ⇒ Object 



424
425
426
 
# File 'ext/duckdb/value.c', line 424

static VALUE value_list_size(VALUE self) {
    return ULL2NUM(duckdb_get_list_size(rbduckdb_get_struct_value(self)->value));
}

#map_key(vidx) ⇒ Object 



506
507
508
509
510
511
512
513
 
# File 'ext/duckdb/value.c', line 506

static VALUE value_map_key(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_map_key(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
    }
    return rbduckdb_value_new(child);
}

#map_size ⇒ Object 



487
488
489
 
# File 'ext/duckdb/value.c', line 487

static VALUE value_map_size(VALUE self) {
    return ULL2NUM(duckdb_get_map_size(rbduckdb_get_struct_value(self)->value));
}

#map_value(vidx) ⇒ Object 



530
531
532
533
534
535
536
537
 
# File 'ext/duckdb/value.c', line 530

static VALUE value_map_value(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_map_value(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
    }
    return rbduckdb_value_new(child);
}

#struct_child(vidx) ⇒ Object 



465
466
467
468
469
470
471
472
 
# File 'ext/duckdb/value.c', line 465

static VALUE value_struct_child(VALUE self, VALUE vidx) {
    duckdb_value child = duckdb_get_struct_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));

    if (child == NULL) {
        rb_raise(rb_eIndexError, "struct index out of range (or the value is not a STRUCT)");
    }
    return rbduckdb_value_new(child);
}

#to_ruby ⇒ Object 



762
763
764
 
# File 'ext/duckdb/value.c', line 762

static VALUE value_to_ruby(VALUE self) {
    return rbduckdb_duckdb_value_to_ruby(rbduckdb_get_struct_value(self)->value);
}