class Sequel::Postgres::PGRange

:nocov:

Constants

ENDLESS_RANGE_NOT_SUPPORTED
STARTLESS_RANGE_NOT_SUPPORTED

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) click to toggle source

Create an empty PGRange with the given database type.

    # File lib/sequel/extensions/pg_range.rb
315 def self.empty(db_type=nil)
316   new(nil, nil, :empty=>true, :db_type=>db_type)
317 end

from_range(range, db_type=nil) click to toggle source

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

    # File lib/sequel/extensions/pg_range.rb
310 def self.from_range(range, db_type=nil)
311   new(range.begin, range.end, :exclude_end=>range.exclude_end?, :db_type=>db_type)
312 end

new(beg, en, opts=OPTS) click to toggle source

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.

    # File lib/sequel/extensions/pg_range.rb
325 def initialize(beg, en, opts=OPTS)
326   @begin = beg
327   @end = en
328   @empty = !!opts[:empty]
329   @exclude_begin = !!opts[:exclude_begin]
330   @exclude_end = !!opts[:exclude_end]
331   @db_type = opts[:db_type]
332   if @empty
333     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?
334   end
335 end

Public Instance Methods

==(other)

Alias for: eql?

===(other) click to toggle source

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.

    # File lib/sequel/extensions/pg_range.rb
395 def ===(other)
396   if eql?(other)
397     true
398   else
399     if valid_ruby_range?
400       to_range === other 
401     else
402       false
403     end
404   end
405 end

cover?(value) click to toggle source

Return whether the value is inside the range.

    # File lib/sequel/extensions/pg_range.rb
344 def cover?(value)
345   return false if empty?
346   b = self.begin
347   return false if b && b.public_send(exclude_begin? ? :>= : :>, value)
348   e = self.end
349   return false if e && e.public_send(exclude_end? ? :<= : :<, value)
350   true
351 end

empty?() click to toggle source

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.

    # File lib/sequel/extensions/pg_range.rb
410 def empty?
411   @empty
412 end

eql?(other) click to toggle source

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.

    # File lib/sequel/extensions/pg_range.rb
357 def eql?(other)
358   case other
359   when PGRange
360     if db_type == other.db_type
361       if empty?
362         other.empty?
363       elsif other.empty?
364         false
365       else
366         [:@begin, :@end, :@exclude_begin, :@exclude_end].all?{|v| instance_variable_get(v) == other.instance_variable_get(v)}
367       end
368     else
369       false
370     end
371   when Range
372     if valid_ruby_range?
373       to_range.eql?(other)
374     else
375       false
376     end
377   else
378     false
379   end
380 end

Also aliased as: ==

exclude_begin?() click to toggle source

Whether the beginning element is excluded from the range.

    # File lib/sequel/extensions/pg_range.rb
415 def exclude_begin?
416   @exclude_begin
417 end

exclude_end?() click to toggle source

Whether the ending element is excluded from the range.

    # File lib/sequel/extensions/pg_range.rb
420 def exclude_end?
421   @exclude_end
422 end

hash() click to toggle source

Make sure equal ranges have the same hash.

    # File lib/sequel/extensions/pg_range.rb
384 def hash
385   if @empty
386     @db_type.hash
387   else
388     [@begin, @end, @exclude_begin, @exclude_end, @db_type].hash
389   end
390 end

inspect() click to toggle source

Support a friendly output

    # File lib/sequel/extensions/pg_range.rb
425 def inspect
426   range = if empty?
427     "empty"
428   else
429     "#{@exclude_begin ? "(" : "["}#{@begin},#{@end}#{@exclude_end ? ")" : "]"}"
430   end
431 
432   "#<#{self.class.name} #{range}#{"::#{@db_type}" if @db_type}>"
433 end

op() click to toggle source

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

    # File lib/sequel/extensions/pg_range_ops.rb
141 def op
142   RangeOp.new(self)
143 end

sequel_auto_param_type(ds) click to toggle source

Allow automatic parameterization for ranges with types, if both start .

    # File lib/sequel/extensions/pg_range.rb
496 def sequel_auto_param_type(ds)
497   "::#{db_type}" if db_type && (!@begin || ds.send(:auto_param_type, @begin)) && (!@end || ds.send(:auto_param_type, @end))
498 end

sql_literal_append(ds, sql) click to toggle source

Append a literalize version of the receiver to the sql.

    # File lib/sequel/extensions/pg_range.rb
436 def sql_literal_append(ds, sql)
437   if (s = @db_type) && !empty?
438     sql << s.to_s << "("
439     ds.literal_append(sql, self.begin)
440     sql << ','
441     ds.literal_append(sql, self.end)
442     sql << ','
443     ds.literal_append(sql, "#{exclude_begin? ? "(" : "["}#{exclude_end? ? ")" : "]"}")
444     sql << ")"
445   else
446     ds.literal_append(sql, unquoted_literal(ds))
447     if s
448       sql << '::' << s.to_s
449     end
450   end
451 end

to_range() click to toggle source

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

    # File lib/sequel/extensions/pg_range.rb
457 def to_range
458   return @range if @range
459   raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
460   raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
461   # :nocov:
462   raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") if STARTLESS_RANGE_NOT_SUPPORTED && !self.begin
463   raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") if ENDLESS_RANGE_NOT_SUPPORTED && !self.end
464   # :nocov:
465   @range = Range.new(self.begin, self.end, exclude_end?)
466 end

unbounded_begin?() click to toggle source

Whether the beginning of the range is unbounded.

    # File lib/sequel/extensions/pg_range.rb
476 def unbounded_begin?
477   self.begin.nil? && !empty?
478 end

unbounded_end?() click to toggle source

Whether the end of the range is unbounded.

    # File lib/sequel/extensions/pg_range.rb
481 def unbounded_end?
482   self.end.nil? && !empty?
483 end

unquoted_literal(ds) click to toggle source

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

    # File lib/sequel/extensions/pg_range.rb
487 def unquoted_literal(ds)
488   if empty?
489     'empty'
490   else
491     "#{exclude_begin? ? "(" : "["}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? ")" : "]"}"
492   end
493 end

valid_ruby_range?() click to toggle source

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.

    # File lib/sequel/extensions/pg_range.rb
471 def valid_ruby_range?
472   !(empty? || exclude_begin? || (STARTLESS_RANGE_NOT_SUPPORTED && !self.begin) || (ENDLESS_RANGE_NOT_SUPPORTED && !self.end))
473 end

Private Instance Methods

escape_value(k, ds) click to toggle source

Escape common range types. Instead of quoting, just backslash escape all special characters.

    # File lib/sequel/extensions/pg_range.rb
504 def escape_value(k, ds)
505   case k
506   when nil
507     ''
508   when Time, Date
509     ds.literal_date_or_time(k, true)
510   when Integer, Float
511     k.to_s
512   when BigDecimal
513     k.to_s('F')
514   when LiteralString
515     k
516   when String
517     if k.empty?
518       '""'
519     else
520       k.gsub(/("|,|\\|\[|\]|\(|\))/, '\\\\\1')
521     end
522   else
523     ds.literal(k).gsub(/("|,|\\|\[|\]|\(|\))/, '\\\\\1')
524   end
525 end