Class: Sequel::Postgres::PGRange

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

Defined Under Namespace

Modules: DatabaseMethods, DatasetMethods Classes: Parser

Constant Summary collapse

RANGE_TYPES =

SEQUEL5: Remove

{}
EMPTY = 
'empty'.freeze
EMPTY_STRING = 
''.freeze
COMMA = 
','.freeze
QUOTED_EMPTY_STRING = 
'""'.freeze
OPEN_PAREN = 
"(".freeze
CLOSE_PAREN = 
")".freeze
OPEN_BRACKET = 
"[".freeze
CLOSE_BRACKET = 
"]".freeze
ESCAPE_RE = 
/("|,|\\|\[|\]|\(|\))/.freeze
ESCAPE_REPLACE = 
'\\\\\1'.freeze
CAST = 
'::'.freeze

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.



432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/sequel/extensions/pg_range.rb', line 432

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.



407
408
409
 
# File 'lib/sequel/extensions/pg_range.rb', line 407

def begin
  @begin
end

#db_type ⇒ Object (readonly)

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



413
414
415
 
# File 'lib/sequel/extensions/pg_range.rb', line 413

def db_type
  @db_type
end

#end ⇒ Object (readonly)

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



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

def end
  @end
end

Class Method Details

.empty(db_type = nil) ⇒ Object

Create an empty PGRange with the given database type.



422
423
424
 
# File 'lib/sequel/extensions/pg_range.rb', line 422

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.



417
418
419
 
# File 'lib/sequel/extensions/pg_range.rb', line 417

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

.register(db_type, opts = OPTS, &block) ⇒ Object

SEQUEL5: Remove



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/sequel/extensions/pg_range.rb', line 107

def self.register(db_type, opts=OPTS, &block)
  Sequel::Deprecation.deprecate("Sequel::Postgres::PGRange.register", "Use Database#register_range_type on a Database instance using the pg_range extension") unless opts[:skip_deprecation_warning]
  db_type = db_type.to_s.dup.freeze

  type_procs = opts[:type_procs] || PG__TYPES
  mod = opts[:typecast_methods_module] || DatabaseMethods
  typecast_method_map = opts[:typecast_method_map] || RANGE_TYPES

  if converter = opts[:converter]
    raise Error, "can't provide both a block and :converter option to register" if block
  else
    converter = block
  end

  if soid = opts[:subtype_oid]
    raise Error, "can't provide both a converter and :subtype_oid option to register" if converter 
    raise Error, "no conversion proc for :subtype_oid=>#{soid.inspect} in PG_TYPES" unless converter = type_procs[soid]
  end

  parser = Parser.new(db_type, converter)

  typecast_method_map[db_type] = db_type.to_sym

  define_range_typecast_method(mod, db_type, parser)

  if oid = opts[:oid]
    if opts[:skip_deprecation_warning]
      def parser.call(s)
        Sequel::Deprecation.deprecate("Conversion proc for #{db_type} added globally by pg_range extension", "Load the pg_range extension into the Database instance")
        super
      end
    end
    type_procs[oid] = parser
  end

  nil
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.



493
494
495
496
497
498
499
500
501
502
503
 
# File 'lib/sequel/extensions/pg_range.rb', line 493

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) 


451
452
453
454
455
456
457
458
 
# File 'lib/sequel/extensions/pg_range.rb', line 451

def cover?(value)
  return false if empty?
  b = self.begin
  return false if b && b.send(exclude_begin? ? :>= : :>, value)
  e = self.end
  return false if e && e.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) 


508
509
510
 
# File 'lib/sequel/extensions/pg_range.rb', line 508

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) 


464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
 
# File 'lib/sequel/extensions/pg_range.rb', line 464

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) 


513
514
515
 
# File 'lib/sequel/extensions/pg_range.rb', line 513

def exclude_begin?
  @exclude_begin
end

#exclude_end? ⇒ Boolean

Whether the ending element is excluded from the range.

Returns:

  • (Boolean) 


518
519
520
 
# File 'lib/sequel/extensions/pg_range.rb', line 518

def exclude_end?
  @exclude_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.



125
126
127
 
# File 'lib/sequel/extensions/pg_range_ops.rb', line 125

def op
  RangeOp.new(self)
end

#sql_literal_append(ds, sql) ⇒ Object

Append a literalize version of the receiver to the sql.



523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/sequel/extensions/pg_range.rb', line 523

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:



541
542
543
544
545
546
547
548
 
# File 'lib/sequel/extensions/pg_range.rb', line 541

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?
  raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") unless self.begin
  raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") unless self.end
  @range = Range.new(self.begin, self.end, exclude_end?)
end

#unbounded_begin? ⇒ Boolean

Whether the beginning of the range is unbounded.

Returns:

  • (Boolean) 


558
559
560
 
# File 'lib/sequel/extensions/pg_range.rb', line 558

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

#unbounded_end? ⇒ Boolean

Whether the end of the range is unbounded.

Returns:

  • (Boolean) 


563
564
565
 
# File 'lib/sequel/extensions/pg_range.rb', line 563

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.



569
570
571
572
573
574
575
 
# File 'lib/sequel/extensions/pg_range.rb', line 569

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) 


553
554
555
 
# File 'lib/sequel/extensions/pg_range.rb', line 553

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