class Sequel::Postgres::PGRange
Constants
- CAST
- CLOSE_BRACKET
- CLOSE_PAREN
- COMMA
- EMPTY
- EMPTY_STRING
- ESCAPE_RE
- ESCAPE_REPLACE
- OPEN_BRACKET
- OPEN_PAREN
- QUOTED_EMPTY_STRING
- RANGE_TYPES
Map of string database type names to type symbols (e.g. 'int4range' => :int4range), used in the schema parsing.
Attributes
The beginning of the range. If nil, the range has an unbounded beginning.
The PostgreSQL database type for the range (e.g. 'int4range').
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.
# File lib/sequel/extensions/pg_range.rb, line 390 def self.empty(db_type=nil) new(nil, nil, :empty=>true, :db_type=>db_type) 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.
# File lib/sequel/extensions/pg_range.rb, line 400 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
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.
# File lib/sequel/extensions/pg_range.rb, line 133 def self.register(db_type, opts=OPTS, &block) db_type = db_type.to_s.dup.freeze type_procs = opts[:type_procs] || PG_TYPES mod = opts[:typecast_methods_module] || DatabaseMethods typecast_method_map = opts[:typecast_method_map] || RANGE_TYPES 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 :subtype_oid option to register" if converter raise Error, "no conversion proc for :subtype_oid=>#{soid.inspect} in PG_TYPES" unless converter = type_procs[soid] end parser = Parser.new(db_type, converter) typecast_method_map[db_type] = db_type.to_sym define_range_typecast_method(mod, db_type, parser) if oid = opts[:oid] type_procs[oid] = parser end nil end
Private Class Methods
Define a private range typecasting method for the given type that uses the parser argument to do the type conversion.
# File lib/sequel/extensions/pg_range.rb, line 166 def self.define_range_typecast_method(mod, type, parser) mod.class_eval do meth = :"typecast_value_#{type}" define_method(meth){|v| typecast_value_pg_range(v, parser)} private meth end end
Public Instance Methods
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, line 461 def ===(other) if eql?(other) true else if valid_ruby_range? to_range === other else false end end end
Return whether the value is inside the range.
# File lib/sequel/extensions/pg_range.rb, line 419 def cover?(value) return false if empty? b = self.begin return false if b && b.send(exclude_begin? ? :>= : :>, value) e = self.end return false if e && e.send(exclude_end? ? :<= : :<, value) true 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.
# File lib/sequel/extensions/pg_range.rb, line 476 def empty? @empty 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.
# File lib/sequel/extensions/pg_range.rb, line 432 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
Whether the beginning element is excluded from the range.
# File lib/sequel/extensions/pg_range.rb, line 481 def exclude_begin? @exclude_begin end
Whether the ending element is excluded from the range.
# File lib/sequel/extensions/pg_range.rb, line 486 def exclude_end? @exclude_end end
Append a literalize version of the receiver to the sql.
# File lib/sequel/extensions/pg_range.rb, line 491 def sql_literal_append(ds, sql) if (s = @db_type) && !empty? sql << s.to_s << OPEN_PAREN ds.literal_append(sql, self.begin) sql << COMMA ds.literal_append(sql, self.end) sql << COMMA ds.literal_append(sql, "#{exclude_begin? ? OPEN_PAREN : OPEN_BRACKET}#{exclude_end? ? CLOSE_PAREN : CLOSE_BRACKET}") sql << CLOSE_PAREN else ds.literal_append(sql, unquoted_literal(ds)) if s sql << CAST << s.to_s end end end
Return a ruby Range object for this instance, if one can be created.
# File lib/sequel/extensions/pg_range.rb, line 509 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
Whether the beginning of the range is unbounded.
# File lib/sequel/extensions/pg_range.rb, line 526 def unbounded_begin? self.begin.nil? && !empty? end
Whether the end of the range is unbounded.
# File lib/sequel/extensions/pg_range.rb, line 531 def unbounded_end? self.end.nil? && !empty? end
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, line 537 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
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, line 521 def valid_ruby_range? !(empty? || exclude_begin? || !self.begin || !self.end) end
Private Instance Methods
Escape common range types. Instead of quoting, just backslash escape all special characters.
# File lib/sequel/extensions/pg_range.rb, line 549 def escape_value(k, ds) case k when nil EMPTY_STRING when Date, Time ds.literal(k)[1...-1] when Integer, Float k.to_s when BigDecimal k.to_s('F') when LiteralString k when String if k.empty? QUOTED_EMPTY_STRING else k.gsub(ESCAPE_RE, ESCAPE_REPLACE) end else ds.literal(k).gsub(ESCAPE_RE, ESCAPE_REPLACE) end end