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 =

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

{}
EMPTY = 
'empty'.freeze
EMPTY_STRING = 
''.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.



334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/sequel/extensions/pg_range.rb', line 334

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.



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

def begin
  @begin
end

#db_type ⇒ Object (readonly)

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



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

def db_type
  @db_type
end

#end ⇒ Object (readonly)

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



312
313
314
 
# File 'lib/sequel/extensions/pg_range.rb', line 312

def end
  @end
end

Class Method Details

.empty(db_type = nil) ⇒ Object

Create an empty PGRange with the given database type.



324
325
326
 
# File 'lib/sequel/extensions/pg_range.rb', line 324

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.



319
320
321
 
# File 'lib/sequel/extensions/pg_range.rb', line 319

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

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.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/sequel/extensions/pg_range.rb', line 98

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

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.



386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/sequel/extensions/pg_range.rb', line 386

def ===(other)
  if eql?(other)
    true
  else
    if valid_ruby_range?
      to_range === other 
    else
      false
    end
  end
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) 


401
402
403
 
# File 'lib/sequel/extensions/pg_range.rb', line 401

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) 


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

def exclude_begin?
  @exclude_begin
end

#exclude_end? ⇒ Boolean

Whether the ending element is excluded from the range.

Returns:

  • (Boolean) 


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

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.



120
121
122
 
# File 'lib/sequel/extensions/pg_range_ops.rb', line 120

def op
  RangeOp.new(self)
end

#sql_literal_append(ds, sql) ⇒ Object

Append a literalize version of the receiver to the sql.



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

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 ⇒ Object

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

Raises:



424
425
426
427
428
429
430
431
 
# File 'lib/sequel/extensions/pg_range.rb', line 424

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) 


441
442
443
 
# File 'lib/sequel/extensions/pg_range.rb', line 441

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

#unbounded_end? ⇒ Boolean

Whether the end of the range is unbounded.

Returns:

  • (Boolean) 


446
447
448
 
# File 'lib/sequel/extensions/pg_range.rb', line 446

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.



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

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? ⇒ 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) 


436
437
438
 
# File 'lib/sequel/extensions/pg_range.rb', line 436

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