Class Sequel::Postgres::PGRange
In: lib/sequel/extensions/pg_range.rb
lib/sequel/extensions/pg_range_ops.rb
Parent: Object

Methods

Included Modules

Sequel::SQL::AliasMethods Enumerable

Classes and Modules

Module Sequel::Postgres::PGRange::DatabaseMethods
Module Sequel::Postgres::PGRange::DatasetMethods
Class Sequel::Postgres::PGRange::Parser

Constants

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

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

Create an empty PGRange with the given database type.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 384
384:       def self.empty(db_type=nil)
385:         new(nil, nil, :empty=>true, :db_type=>db_type)
386:       end

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

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 379
379:       def self.from_range(range, db_type=nil)
380:         new(range.begin, range.end, :exclude_end=>range.exclude_end?, :db_type=>db_type)
381:       end

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.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 394
394:       def initialize(beg, en, opts=OPTS)
395:         @begin = beg
396:         @end = en
397:         @empty = !!opts[:empty]
398:         @exclude_begin = !!opts[:exclude_begin]
399:         @exclude_end = !!opts[:exclude_end]
400:         @db_type = opts[:db_type]
401:         if @empty
402:           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?
403:         end
404:       end

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.
:type_procs :A hash mapping oids to conversion procs, used for setting the default :converter for :subtype_oid. Defaults to the global Sequel::Postgres::PG_TYPES.
:typecast_method_map :The map in which to place the database type string to type symbol mapping. Defaults to RANGE_TYPES.
:typecast_methods_module :If given, a module object to add the typecasting method to. Defaults to DatabaseMethods.

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

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 133
133:       def self.register(db_type, opts=OPTS, &block)
134:         db_type = db_type.to_s.dup.freeze
135: 
136:         type_procs = opts[:type_procs] || PG_TYPES
137:         mod = opts[:typecast_methods_module] || DatabaseMethods
138:         typecast_method_map = opts[:typecast_method_map] || RANGE_TYPES
139: 
140:         if converter = opts[:converter]
141:           raise Error, "can't provide both a block and :converter option to register" if block
142:         else
143:           converter = block
144:         end
145: 
146:         if soid = opts[:subtype_oid]
147:           raise Error, "can't provide both a converter and :subtype_oid option to register" if converter 
148:           raise Error, "no conversion proc for :subtype_oid=>#{soid.inspect} in PG_TYPES" unless converter = type_procs[soid]
149:         end
150: 
151:         parser = Parser.new(db_type, converter)
152: 
153:         typecast_method_map[db_type] = db_type.to_sym
154: 
155:         define_range_typecast_method(mod, db_type, parser)
156: 
157:         if oid = opts[:oid]
158:           type_procs[oid] = parser
159:         end
160: 
161:         nil
162:       end

Public Instance methods

==(other)

Alias for eql?

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.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 455
455:       def ===(other)
456:         if eql?(other)
457:           true
458:         else
459:           if valid_ruby_range?
460:             to_range === other 
461:           else
462:             false
463:           end
464:         end
465:       end

Return whether the value is inside the range.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 413
413:       def cover?(value)
414:         return false if empty?
415:         b = self.begin
416:         return false if b && b.send(exclude_begin? ? :>= : :>, value)
417:         e = self.end
418:         return false if e && e.send(exclude_end? ? :<= : :<, value)
419:         true
420:       end

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.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 470
470:       def empty?
471:         @empty
472:       end

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.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 426
426:       def eql?(other)
427:         case other
428:         when PGRange
429:           if db_type == other.db_type
430:             if empty?
431:               other.empty?
432:             elsif other.empty?
433:               false
434:             else
435:               [:@begin, :@end, :@exclude_begin, :@exclude_end].all?{|v| instance_variable_get(v) == other.instance_variable_get(v)}
436:             end
437:           else
438:             false
439:           end
440:         when Range
441:           if valid_ruby_range?
442:             to_range.eql?(other)
443:           else
444:             false
445:           end
446:         else
447:           false
448:         end
449:       end

Whether the beginning element is excluded from the range.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 475
475:       def exclude_begin?
476:         @exclude_begin
477:       end

Whether the ending element is excluded from the range.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 480
480:       def exclude_end?
481:         @exclude_end
482:       end

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

[Source]

     # File lib/sequel/extensions/pg_range_ops.rb, line 124
124:         def op
125:           RangeOp.new(self)
126:         end

Append a literalize version of the receiver to the sql.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 485
485:       def sql_literal_append(ds, sql)
486:         if (s = @db_type) && !empty?
487:           sql << s.to_s << OPEN_PAREN
488:           ds.literal_append(sql, self.begin)
489:           sql << COMMA
490:           ds.literal_append(sql, self.end)
491:           sql << COMMA
492:           ds.literal_append(sql, "#{exclude_begin? ? OPEN_PAREN : OPEN_BRACKET}#{exclude_end? ? CLOSE_PAREN : CLOSE_BRACKET}")
493:           sql << CLOSE_PAREN
494:         else
495:           ds.literal_append(sql, unquoted_literal(ds))
496:           if s
497:             sql << CAST << s.to_s
498:           end
499:         end
500:       end

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

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 503
503:       def to_range
504:         return @range if @range
505:         raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
506:         raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
507:         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") unless self.begin
508:         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") unless self.end
509:         @range = Range.new(self.begin, self.end, exclude_end?)
510:       end

Whether the beginning of the range is unbounded.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 520
520:       def unbounded_begin?
521:         self.begin.nil? && !empty?
522:       end

Whether the end of the range is unbounded.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 525
525:       def unbounded_end?
526:         self.end.nil? && !empty?
527:       end

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

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 531
531:       def unquoted_literal(ds)
532:         if empty?
533:           EMPTY
534:         else
535:           "#{exclude_begin? ? OPEN_PAREN : OPEN_BRACKET}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? CLOSE_PAREN : CLOSE_BRACKET}"
536:         end
537:       end

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.

[Source]

     # File lib/sequel/extensions/pg_range.rb, line 515
515:       def valid_ruby_range?
516:         !(empty? || exclude_begin? || !self.begin || !self.end)
517:       end

[Validate]