Class: Sequel::Postgres::PGRange
- Includes:
- Enumerable, SQL::AliasMethods
- Defined in:
- lib/sequel/extensions/pg_range.rb,
lib/sequel/extensions/pg_range_ops.rb
Defined Under Namespace
Modules: DatabaseMethods, DatasetMethods Classes: Parser
Constant Summary collapse
- 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
Instance Attribute Summary collapse
-
#begin ⇒ Object
readonly
The beginning of the range.
-
#db_type ⇒ Object
readonly
The PostgreSQL database type for the range (e.g. ‘int4range’).
-
#end ⇒ Object
readonly
The end of the range.
Class Method Summary collapse
-
.empty(db_type = nil) ⇒ Object
Create an empty PGRange with the given database type.
-
.from_range(range, db_type = nil) ⇒ Object
Create a new PGRange instance using the beginning and ending of the ruby Range, with the given db_type.
-
.register(db_type, opts = OPTS, &block) ⇒ Object
Registers a range type that the extension should handle.
Instance Method Summary collapse
-
#===(other) ⇒ Object
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.
-
#empty? ⇒ Boolean
Whether this range is empty (has no points).
-
#eql?(other) ⇒ Boolean
(also: #==)
Consider the receiver equal to other PGRange instances with the same beginning, ending, exclusions, and database type.
-
#exclude_begin? ⇒ Boolean
Whether the beginning element is excluded from the range.
-
#exclude_end? ⇒ Boolean
Whether the ending element is excluded from the range.
-
#initialize(beg, en, opts = OPTS) ⇒ PGRange
constructor
Initialize a new PGRange instance.
-
#op ⇒ Object
Wrap the PGRange instance in an RangeOp, allowing you to easily use the PostgreSQL range functions and operators with literal ranges.
-
#sql_literal_append(ds, sql) ⇒ Object
Append a literalize version of the receiver to the sql.
-
#to_range ⇒ Object
Return a ruby Range object for this instance, if one can be created.
-
#unbounded_begin? ⇒ Boolean
Whether the beginning of the range is unbounded.
-
#unbounded_end? ⇒ Boolean
Whether the end of the range is unbounded.
-
#unquoted_literal(ds) ⇒ Object
Return a string containing the unescaped version of the range.
-
#valid_ruby_range? ⇒ Boolean
Whether or not this PGRange is a valid ruby range.
Methods included from SQL::AliasMethods
Constructor Details
#initialize(beg, en, opts = OPTS) ⇒ PGRange
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.
331 332 333 334 335 336 337 338 339 340 341 |
# File 'lib/sequel/extensions/pg_range.rb', line 331 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 |
Instance Attribute Details
#begin ⇒ Object (readonly)
The beginning of the range. If nil, the range has an unbounded beginning.
306 307 308 |
# File 'lib/sequel/extensions/pg_range.rb', line 306 def begin @begin end |
#db_type ⇒ Object (readonly)
The PostgreSQL database type for the range (e.g. ‘int4range’).
312 313 314 |
# File 'lib/sequel/extensions/pg_range.rb', line 312 def db_type @db_type end |
#end ⇒ Object (readonly)
The end of the range. If nil, the range has an unbounded ending.
309 310 311 |
# File 'lib/sequel/extensions/pg_range.rb', line 309 def end @end end |
Class Method Details
.empty(db_type = nil) ⇒ Object
Create an empty PGRange with the given database type.
321 322 323 |
# File 'lib/sequel/extensions/pg_range.rb', line 321 def self.empty(db_type=nil) new(nil, nil, :empty=>true, :db_type=>db_type) end |
.from_range(range, db_type = nil) ⇒ Object
Create a new PGRange instance using the beginning and ending of the ruby Range, with the given db_type.
316 317 318 |
# File 'lib/sequel/extensions/pg_range.rb', line 316 def self.from_range(range, db_type=nil) new(range.begin, range.end, :exclude_end=>range.exclude_end?, :db_type=>db_type) end |
.register(db_type, opts = OPTS, &block) ⇒ Object
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.
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 |
# File 'lib/sequel/extensions/pg_range.rb', line 95 def self.register(db_type, opts=OPTS, &block) db_type = db_type.to_s.dup.freeze 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 :scalar_oid option to register" if converter raise Error, "no conversion proc for :scalar_oid=>#{soid.inspect} in PG_TYPES" unless converter = PG_TYPES[soid] end parser = Parser.new(db_type, converter) RANGE_TYPES[db_type] = db_type.to_sym DatabaseMethods.define_range_typecast_method(db_type, parser) if oid = opts[:oid] Sequel::Postgres::PG_TYPES[oid] = parser end nil end |
Instance Method Details
#===(other) ⇒ Object
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.
383 384 385 386 387 388 389 390 391 392 393 |
# File 'lib/sequel/extensions/pg_range.rb', line 383 def ===(other) if eql?(other) true else if valid_ruby_range? to_range === other else false end end end |
#empty? ⇒ Boolean
Whether this range is empty (has no points).
396 397 398 |
# File 'lib/sequel/extensions/pg_range.rb', line 396 def empty? @empty end |
#eql?(other) ⇒ Boolean Also known as: ==
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.
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 |
# File 'lib/sequel/extensions/pg_range.rb', line 354 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 |
#exclude_begin? ⇒ Boolean
Whether the beginning element is excluded from the range.
401 402 403 |
# File 'lib/sequel/extensions/pg_range.rb', line 401 def exclude_begin? @exclude_begin end |
#exclude_end? ⇒ Boolean
Whether the ending element is excluded from the range.
406 407 408 |
# File 'lib/sequel/extensions/pg_range.rb', line 406 def exclude_end? @exclude_end end |
#op ⇒ Object
Wrap the PGRange instance in an RangeOp, allowing you to easily use the PostgreSQL range functions and operators with literal ranges.
119 120 121 |
# File 'lib/sequel/extensions/pg_range_ops.rb', line 119 def op RangeOp.new(self) end |
#sql_literal_append(ds, sql) ⇒ Object
Append a literalize version of the receiver to the sql.
411 412 413 414 415 416 |
# File 'lib/sequel/extensions/pg_range.rb', line 411 def sql_literal_append(ds, sql) ds.literal_append(sql, unquoted_literal(ds)) if s = @db_type sql << CAST << s.to_s end end |
#to_range ⇒ Object
Return a ruby Range object for this instance, if one can be created.
419 420 421 422 423 424 425 426 |
# File 'lib/sequel/extensions/pg_range.rb', line 419 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 |
#unbounded_begin? ⇒ Boolean
Whether the beginning of the range is unbounded.
436 437 438 |
# File 'lib/sequel/extensions/pg_range.rb', line 436 def unbounded_begin? self.begin.nil? && !empty? end |
#unbounded_end? ⇒ Boolean
Whether the end of the range is unbounded.
441 442 443 |
# File 'lib/sequel/extensions/pg_range.rb', line 441 def unbounded_end? self.end.nil? && !empty? end |
#unquoted_literal(ds) ⇒ Object
Return a string containing the unescaped version of the range. Separated out for use by the bound argument code.
447 448 449 450 451 452 453 |
# File 'lib/sequel/extensions/pg_range.rb', line 447 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 |
#valid_ruby_range? ⇒ Boolean
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.
431 432 433 |
# File 'lib/sequel/extensions/pg_range.rb', line 431 def valid_ruby_range? !(empty? || exclude_begin? || !self.begin || !self.end) end |