class Sequel::Postgres::PGRange

  1. lib/sequel/extensions/pg_range.rb
  2. lib/sequel/extensions/pg_range_ops.rb
  3. show all
Parent: Postgres

Included modules

  1. Sequel::SQL::AliasMethods
  2. Enumerable

Constants

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

Map of string database type names to type symbols (e.g. ‘int4range’ => :int4range), used in the schema parsing.

Public Instance Aliases

== -> eql?

Attributes

begin [R]

The beginning of the range. If nil, the range has an unbounded beginning.
db_type [R]

The PostgreSQL database type for the range (e.g. ‘int4range’).
end [R]

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

Public Class methods

empty (db_type=nil)

Create an empty PGRange with the given database type.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 321
def self.empty(db_type=nil)
  new(nil, nil, :empty=>true, :db_type=>db_type)
end
from_range (range, db_type=nil)

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

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 316
def self.from_range(range, db_type=nil)
  new(range.begin, range.end, :exclude_end=>range.exclude_end?, :db_type=>db_type)
end
new (beg, en, opts=OPTS)

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.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 331
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
register (db_type, opts=OPTS, &block)

Registers a range type that the extension should handle. Makes a Database instance that has been extended with DatabaseMethods recognize the range type given and set up the appropriate typecasting. Also sets up automatic typecasting for the native postgres adapter, so that on retrieval, the values are automatically converted to PGRange instances. The #db_type argument should be the name of the range type. Accepts the following options:

:converter

A callable object (e.g. Proc), that is called with the start or end of the range (usually a string), and should return the appropriate typecasted object.

:oid

The PostgreSQL OID for the range type. This is used by the Sequel postgres adapter to set up automatic type conversion on retrieval from the database.

:subtype_oid

Should be the PostgreSQL OID for the range’s subtype. If given,

automatically sets the :converter option by looking for scalar conversion
proc.

If a block is given, it is treated as the :converter option.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 95
def self.register(db_type, opts=OPTS, &block)
  db_type = db_type.to_s.dup.freeze

  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 :scalar_oid option to register" if converter 
    raise Error, "no conversion proc for :scalar_oid=>#{soid.inspect} in PG_TYPES" unless converter = PG_TYPES[soid]
  end

  parser = Parser.new(db_type, converter)

  RANGE_TYPES[db_type] = db_type.to_sym

  DatabaseMethods.define_range_typecast_method(db_type, parser)

  if oid = opts[:oid]
    Sequel::Postgres::PG_TYPES[oid] = parser
  end

  nil
end

Public Instance methods

=== (other)

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.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 383
def ===(other)
  if eql?(other)
    true
  else
    if valid_ruby_range?
      to_range === other 
    else
      false
    end
  end
end
empty? ()

Whether this range is empty (has no points).

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 396
def empty?
  @empty
end
eql? (other)

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.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 354
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? ()

Whether the beginning element is excluded from the range.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 401
def exclude_begin?
  @exclude_begin
end
exclude_end? ()

Whether the ending element is excluded from the range.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 406
def exclude_end?
  @exclude_end
end
op ()

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

[show source] 
# File lib/sequel/extensions/pg_range_ops.rb, line 119
def op
  RangeOp.new(self)
end
sql_literal_append (ds, sql)

Append a literalize version of the receiver to the sql.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 411
def sql_literal_append(ds, sql)
  ds.literal_append(sql, unquoted_literal(ds))
  if s = @db_type
    sql << CAST << s.to_s
  end
end
to_range ()

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

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 419
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? ()

Whether the beginning of the range is unbounded.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 436
def unbounded_begin?
  self.begin.nil? && !empty?
end
unbounded_end? ()

Whether the end of the range is unbounded.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 441
def unbounded_end?
  self.end.nil? && !empty?
end
unquoted_literal (ds)

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

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 447
def unquoted_literal(ds)
  if empty?
    EMPTY
  else
    "#{exclude_begin? ? OPEN_PAREN : OPEN_BRACKET}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? CLOSE_PAREN : CLOSE_BRACKET}"
  end
end
valid_ruby_range? ()

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.

[show source] 
# File lib/sequel/extensions/pg_range.rb, line 431
def valid_ruby_range?
  !(empty? || exclude_begin? || !self.begin || !self.end)
end