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

### Methods

== === empty empty? eql? exclude_begin? exclude_end? from_range new op register sql_literal_append to_range unbounded_begin? unbounded_end? unquoted_literal valid_ruby_range?

### Included Modules

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

empty(db_type=nil)

Create an empty PGRange with the given database type.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 304
    304:       def self.empty(db_type=nil)
    305:         new(nil, nil, :empty=>true, :db_type=>db_type)
    306:       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.

[Source]

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

new(beg, en, 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.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 314
    314:       def initialize(beg, en, opts={})
    315:         @begin = beg
    316:         @end = en
    317:         @empty = !!opts[:empty]
    318:         @exclude_begin = !!opts[:exclude_begin]
    319:         @exclude_end = !!opts[:exclude_end]
    320:         @db_type = opts[:db_type]
    321:         if @empty
    322:           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?
    323:         end
    324:       end

register(db_type, 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.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 93
     93:       def self.register(db_type, opts={}, &block)
     94:         db_type = db_type.to_s.dup.freeze
     95:
     96:         if converter = opts[:converter]
     97:           raise Error, "can't provide both a block and :converter option to register" if block
     98:         else
     99:           converter = block
    100:         end
    101:
    102:         if soid = opts[:subtype_oid]
    103:           raise Error, "can't provide both a converter and :scalar_oid option to register" if converter
    104:           raise Error, "no conversion proc for :scalar_oid=>#{soid.inspect} in PG_TYPES" unless converter = PG_TYPES[soid]
    105:         end
    106:
    107:         parser = Parser.new(db_type, converter)
    108:
    109:         RANGE_TYPES[db_type] = db_type.to_sym
    110:
    111:         DatabaseMethods.define_range_typecast_method(db_type, parser)
    112:
    113:         if oid = opts[:oid]
    114:           Sequel::Postgres::PG_TYPES[oid] = parser
    115:         end
    116:
    117:         nil
    118:       end

### Public Instance methods

==(other)

Alias for eql?

===(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.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 366
    366:       def ===(other)
    367:         if eql?(other)
    368:           true
    369:         else
    370:           if valid_ruby_range?
    371:             to_range === other
    372:           else
    373:             false
    374:           end
    375:         end
    376:       end

empty?()

Whether this range is empty (has no points).

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 379
    379:       def empty?
    380:         @empty
    381:       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.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 337
    337:       def eql?(other)
    338:         case other
    339:         when PGRange
    340:           if db_type == other.db_type
    341:             if empty?
    342:               other.empty?
    343:             elsif other.empty?
    344:               false
    345:             else
    346:               [:@begin, :@end, :@exclude_begin, :@exclude_end].all?{|v| instance_variable_get(v) == other.instance_variable_get(v)}
    347:             end
    348:           else
    349:             false
    350:           end
    351:         when Range
    352:           if valid_ruby_range?
    353:             to_range.eql?(other)
    354:           else
    355:             false
    356:           end
    357:         else
    358:           false
    359:         end
    360:       end

exclude_begin?()

Whether the beginning element is excluded from the range.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 384
    384:       def exclude_begin?
    385:         @exclude_begin
    386:       end

exclude_end?()

Whether the ending element is excluded from the range.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 389
    389:       def exclude_end?
    390:         @exclude_end
    391:       end

op()

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 118
    118:         def op
    119:           RangeOp.new(self)
    120:         end

sql_literal_append(ds, sql)

Append a literalize version of the receiver to the sql.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 394
    394:       def sql_literal_append(ds, sql)
    395:         ds.literal_append(sql, unquoted_literal(ds))
    396:         if s = @db_type
    397:           sql << CAST << s.to_s
    398:         end
    399:       end

to_range()

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

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 402
    402:       def to_range
    403:         return @range if @range
    404:         raise(Error, "cannot create ruby range for an empty PostgreSQL range") if empty?
    405:         raise(Error, "cannot create ruby range when PostgreSQL range excludes beginning element") if exclude_begin?
    406:         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded beginning") unless self.begin
    407:         raise(Error, "cannot create ruby range when PostgreSQL range has unbounded ending") unless self.end
    408:         @range = Range.new(self.begin, self.end, exclude_end?)
    409:       end

unbounded_begin?()

Whether the beginning of the range is unbounded.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 419
    419:       def unbounded_begin?
    420:         self.begin.nil? && !empty?
    421:       end

unbounded_end?()

Whether the end of the range is unbounded.

[Source]

         # File lib/sequel/extensions/pg_range.rb, line 424
    424:       def unbounded_end?
    425:         self.end.nil? && !empty?
    426:       end

unquoted_literal(ds)

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 430
    430:       def unquoted_literal(ds)
    431:         if empty?
    432:           EMPTY
    433:         else
    434:           "#{exclude_begin? ? OPEN_PAREN : OPEN_BRACKET}#{escape_value(self.begin, ds)},#{escape_value(self.end, ds)}#{exclude_end? ? CLOSE_PAREN : CLOSE_BRACKET}"
    435:         end
    436:       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.

[Source]

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

[Validate]