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

Also aliased as: to_s

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
497 def sequel_auto_param_type(ds)
498   "::#{db_type}" if db_type && (!@begin || ds.send(:auto_param_type, @begin)) && (!@end || ds.send(:auto_param_type, @end))
499 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
437 def sql_literal_append(ds, sql)
438   if (s = @db_type) && !empty?
439     sql << s.to_s << "("
440     ds.literal_append(sql, self.begin)
441     sql << ','
442     ds.literal_append(sql, self.end)
443     sql << ','
444     ds.literal_append(sql, "#{exclude_begin? ? "(" : "["}#{exclude_end? ? ")" : "]"}")
445     sql << ")"
446   else
447     ds.literal_append(sql, unquoted_literal(ds))
448     if s
449       sql << '::' << s.to_s
450     end
451   end
452 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
458 def to_range
459   return @range if @range
460   raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
461   raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
462   # :nocov:
463   raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") if STARTLESS_RANGE_NOT_SUPPORTED && !self.begin
464   raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") if ENDLESS_RANGE_NOT_SUPPORTED && !self.end
465   # :nocov:
466   @range = Range.new(self.begin, self.end, exclude_end?)
467 end

to_s()

Alias for: inspect

unbounded_begin?() click to toggle source

Whether the beginning of the range is unbounded.

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

unbounded_end?() click to toggle source

Whether the end of the range is unbounded.

    # File lib/sequel/extensions/pg_range.rb
482 def unbounded_end?
483   self.end.nil? && !empty?
484 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
488 def unquoted_literal(ds)
489   if empty?
490     'empty'
491   else
492     "#{exclude_begin? ? "(" : "["}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? ")" : "]"}"
493   end
494 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
472 def valid_ruby_range?
473   !(empty? || exclude_begin? || (STARTLESS_RANGE_NOT_SUPPORTED && !self.begin) || (ENDLESS_RANGE_NOT_SUPPORTED && !self.end))
474 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
505 def escape_value(k, ds)
506   case k
507   when nil
508     ''
509   when Time, Date
510     ds.literal_date_or_time(k, true)
511   when Integer, Float
512     k.to_s
513   when BigDecimal
514     k.to_s('F')
515   when LiteralString
516     k
517   when String
518     if k.empty?
519       '""'
520     else
521       k.gsub(/("|,|\\|\[|\]|\(|\))/, '\\\\\1')
522     end
523   else
524     ds.literal(k).gsub(/("|,|\\|\[|\]|\(|\))/, '\\\\\1')
525   end
526 end