Class: Sequel::Postgres::PGRange

Inherits:
Object
  • Object
show all
Includes:
Enumerable, SQL::AliasMethods
Defined in:
lib/sequel/extensions/pg_range_ops.rb,
lib/sequel/extensions/pg_range.rb

Overview

:nocov:

Defined Under Namespace

Modules: DatabaseMethods, DatasetMethods Classes: Parser

Constant Summary collapse

ENDLESS_RANGE_NOT_SUPPORTED = 
RUBY_VERSION < '2.6'
STARTLESS_RANGE_NOT_SUPPORTED = 
RUBY_VERSION < '2.7'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SQL::AliasMethods

#as

Constructor Details

#initialize(beg, en, opts = OPTS) ⇒ PGRange

Initialize a new PGRange instance. Accepts the following options:

:db_type

The PostgreSQL database type for the range.

:empty

Whether the range is empty (has no points)

:exclude_begin

Whether the beginning element is excluded from the range.

:exclude_end

Whether the ending element is excluded from the range.



325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/sequel/extensions/pg_range.rb', line 325

def initialize(beg, en, opts=OPTS)
  @begin = beg
  @end = en
  @empty = !!opts[:empty]
  @exclude_begin = !!opts[:exclude_begin]
  @exclude_end = !!opts[:exclude_end]
  @db_type = opts[:db_type]
  if @empty
    raise(Error, 'cannot have an empty range with either a beginning or ending') unless @begin.nil? && @end.nil? && opts[:exclude_begin].nil? && opts[:exclude_end].nil?
  end
end

Instance Attribute Details

#begin ⇒ Object (readonly)

The beginning of the range. If nil, the range has an unbounded beginning.



300
301
302
 
# File 'lib/sequel/extensions/pg_range.rb', line 300

def begin
  @begin
end

#db_type ⇒ Object (readonly)

The PostgreSQL database type for the range (e.g. ‘int4range’).



306
307
308
 
# File 'lib/sequel/extensions/pg_range.rb', line 306

def db_type
  @db_type
end

#end ⇒ Object (readonly)

The end of the range. If nil, the range has an unbounded ending.



303
304
305
 
# File 'lib/sequel/extensions/pg_range.rb', line 303

def end
  @end
end

Class Method Details

.empty(db_type = nil) ⇒ Object

Create an empty PGRange with the given database type.



315
316
317
 
# File 'lib/sequel/extensions/pg_range.rb', line 315

def self.empty(db_type=nil)
  new(nil, nil, :empty=>true, :db_type=>db_type)
end

.from_range(range, db_type = nil) ⇒ Object

Create a new PGRange instance using the beginning and ending of the ruby Range, with the given db_type.



310
311
312
 
# File 'lib/sequel/extensions/pg_range.rb', line 310

def self.from_range(range, db_type=nil)
  new(range.begin, range.end, :exclude_end=>range.exclude_end?, :db_type=>db_type)
end

Instance Method Details

#===(other) ⇒ Object

Allow PGRange values in case statements, where they return true if they are equal to each other using eql?, or if this PGRange can be converted to a Range, delegating to that range.



395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/sequel/extensions/pg_range.rb', line 395

def ===(other)
  if eql?(other)
    true
  else
    if valid_ruby_range?
      to_range === other 
    else
      false
    end
  end
end

#cover?(value) ⇒ Boolean

Return whether the value is inside the range.

Returns:

  • (Boolean) 


344
345
346
347
348
349
350
351
 
# File 'lib/sequel/extensions/pg_range.rb', line 344

def cover?(value)
  return false if empty?
  b = self.begin
  return false if b && b.public_send(exclude_begin? ? :>= : :>, value)
  e = self.end
  return false if e && e.public_send(exclude_end? ? :<= : :<, value)
  true
end

#empty? ⇒ Boolean

Whether this range is empty (has no points). Note that for manually created ranges (ones not retrieved from the database), this will only be true if the range was created using the :empty option.

Returns:

  • (Boolean) 


410
411
412
 
# File 'lib/sequel/extensions/pg_range.rb', line 410

def empty?
  @empty
end

#eql?(other) ⇒ Boolean Also known as: ==

Consider the receiver equal to other PGRange instances with the same beginning, ending, exclusions, and database type. Also consider it equal to Range instances if this PGRange can be converted to a a Range and those ranges are equal.

Returns:

  • (Boolean) 


357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/sequel/extensions/pg_range.rb', line 357

def eql?(other)
  case other
  when PGRange
    if db_type == other.db_type
      if empty?
        other.empty?
      elsif other.empty?
        false
      else
        [:@begin, :@end, :@exclude_begin, :@exclude_end].all?{|v| instance_variable_get(v) == other.instance_variable_get(v)}
      end
    else
      false
    end
  when Range
    if valid_ruby_range?
      to_range.eql?(other)
    else
      false
    end
  else
    false
  end
end

#exclude_begin? ⇒ Boolean

Whether the beginning element is excluded from the range.

Returns:

  • (Boolean) 


415
416
417
 
# File 'lib/sequel/extensions/pg_range.rb', line 415

def exclude_begin?
  @exclude_begin
end

#exclude_end? ⇒ Boolean

Whether the ending element is excluded from the range.

Returns:

  • (Boolean) 


420
421
422
 
# File 'lib/sequel/extensions/pg_range.rb', line 420

def exclude_end?
  @exclude_end
end

#hash ⇒ Object

Make sure equal ranges have the same hash.



384
385
386
387
388
389
390
 
# File 'lib/sequel/extensions/pg_range.rb', line 384

def hash
  if @empty
    @db_type.hash
  else
    [@begin, @end, @exclude_begin, @exclude_end, @db_type].hash
  end
end

#op ⇒ Object

Wrap the PGRange instance in an RangeOp, allowing you to easily use the PostgreSQL range functions and operators with literal ranges.



141
142
143
 
# File 'lib/sequel/extensions/pg_range_ops.rb', line 141

def op
  RangeOp.new(self)
end

#sequel_auto_param_type(ds) ⇒ Object

Allow automatic parameterization for ranges with types.



485
486
487
 
# File 'lib/sequel/extensions/pg_range.rb', line 485

def sequel_auto_param_type(ds)
  "::#{db_type}" if db_type
end

#sql_literal_append(ds, sql) ⇒ Object

Append a literalize version of the receiver to the sql.



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/sequel/extensions/pg_range.rb', line 425

def sql_literal_append(ds, sql)
  if (s = @db_type) && !empty?
    sql << s.to_s << "("
    ds.literal_append(sql, self.begin)
    sql << ','
    ds.literal_append(sql, self.end)
    sql << ','
    ds.literal_append(sql, "#{exclude_begin? ? "(" : "["}#{exclude_end? ? ")" : "]"}")
    sql << ")"
  else
    ds.literal_append(sql, unquoted_literal(ds))
    if s
      sql << '::' << s.to_s
    end
  end
end

#to_range ⇒ Object

Return a ruby Range object for this instance, if one can be created.

Raises:



446
447
448
449
450
451
452
453
454
455
 
# File 'lib/sequel/extensions/pg_range.rb', line 446

def to_range
  return @range if @range
  raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
  raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
  # :nocov:
  raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") if STARTLESS_RANGE_NOT_SUPPORTED && !self.begin
  raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") if ENDLESS_RANGE_NOT_SUPPORTED && !self.end
  # :nocov:
  @range = Range.new(self.begin, self.end, exclude_end?)
end

#unbounded_begin? ⇒ Boolean

Whether the beginning of the range is unbounded.

Returns:

  • (Boolean) 


465
466
467
 
# File 'lib/sequel/extensions/pg_range.rb', line 465

def unbounded_begin?
  self.begin.nil? && !empty?
end

#unbounded_end? ⇒ Boolean

Whether the end of the range is unbounded.

Returns:

  • (Boolean) 


470
471
472
 
# File 'lib/sequel/extensions/pg_range.rb', line 470

def unbounded_end?
  self.end.nil? && !empty?
end

#unquoted_literal(ds) ⇒ Object

Return a string containing the unescaped version of the range. Separated out for use by the bound argument code.



476
477
478
479
480
481
482
 
# File 'lib/sequel/extensions/pg_range.rb', line 476

def unquoted_literal(ds)
  if empty?
    'empty'
  else
    "#{exclude_begin? ? "(" : "["}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? ")" : "]"}"
  end
end

#valid_ruby_range? ⇒ Boolean

Whether or not this PGRange is a valid ruby range. In order to be a valid ruby range, it must have a beginning and an ending (no unbounded ranges), and it cannot exclude the beginning element.

Returns:

  • (Boolean) 


460
461
462
 
# File 'lib/sequel/extensions/pg_range.rb', line 460

def valid_ruby_range?
  !(empty? || exclude_begin? || (STARTLESS_RANGE_NOT_SUPPORTED && !self.begin) || (ENDLESS_RANGE_NOT_SUPPORTED && !self.end))
end