Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

1572 lines (1126 sloc) 43.353 kb
=begin
= PL/Ruby
* ((<Defining function in PL Ruby>))
* ((<Function returning SET (SFRM Materialize)>))
* ((<Function returning SET (ExprMultiResult)>))
* ((<Trigger procedures in PL Ruby>))
* ((<plruby_singleton_methods>))
* ((<Conversion>))
* ((<Class and modules>))
* ((<module PL>)) : general module
* ((<class PL::Plan>)) : class for prepared plans
* ((<class PL::Cursor>)) : class for cursors
* ((<class PL::Transaction>)) : class for transactions (8.0)
* ((<class BitString>))
* ((<class Tinterval>))
* ((<class NetAddr>))
* ((<class MacAddr>))
* ((<class Box>))
* ((<class Circle>))
* ((<class Path>))
* ((<class Point>))
* ((<class Polygon>))
* ((<class Segment>))
PL/Ruby is a loadable procedural language for the PostgreSQL database
system that enables the Ruby language to create functions and trigger
procedures.
Functions and triggers are defined as singleton methods of the module
PLtemp.
= WARNING
((*if PL/Ruby was compiled with ((%--disable-conversion%)),
all arguments (to the function or the triggers) are passed as string
values, except for NULL values represented by ((%Qnil%)).*))
((*In this case you must explicitely call a conversion function (like to_i)
if you want to use an argument as an integer*))
== Defining function in PL Ruby
To create a function in the PL/Ruby language use the syntax
CREATE FUNCTION funcname(arguments_type) RETURNS type AS '
# PL/Ruby function body
' LANGUAGE 'plruby';
when calling the function in a query, the arguments are given
in the array ((%args%)). To create a little max
function returning the higher of two int4 values write :
CREATE FUNCTION ruby_max(int4, int4) RETURNS int4 AS '
if args[0] > args[1]
return args[0]
else
return args[1]
end
' LANGUAGE 'plruby';
Tuple arguments are given as hash. Here is an example that defines
the overpaid_2 function (as found in the older Postgres documentation)
in PL/Ruby.
CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
args[0]["salary"] > 200000 ||
(args[0]["salary"] > 100000 && args[0]["age"] < 30)
' LANGUAGE 'plruby';
=== Warning : with PostgreSQL >= 7.4 "array" are given as a ruby Array
For example to define a function (int4[], int4) and return int4[],
in version < 7.4 you write
CREATE FUNCTION ruby_int4_accum(_int4, int4) RETURNS _int4 AS '
if /\\{(\\d+),(\\d+)\\}/ =~ args[0]
a, b = $1, $2
newsum = a + args[1]
newcnt = b + 1
else
raise "unexpected value #{args[0]}"
end
"{#{newsum},#{newcnt}}"
' LANGUAGE 'plruby';
This must now (>= 7.4) be written
CREATE FUNCTION ruby_int4_accum(_int4, int4) RETURNS _int4 AS '
a = args[0]
[a[0] + args[1], a[1] + 1]
' LANGUAGE 'plruby';
=== Release PostgreSQL 8.0
With this version, plruby can have named arguments and the previous functions
can be written
CREATE FUNCTION ruby_max(a int4, b int4) RETURNS int4 AS '
if a > b
a
else
b
end
' LANGUAGE 'plruby';
CREATE FUNCTION overpaid_2 (emp EMP) RETURNS bool AS '
emp["salary"] > 200000 ||
(emp["salary"] > 100000 && emp["age"] < 30)
' LANGUAGE 'plruby';
With this version, you can also use transaction. For example
plruby_test=# create table tu (a int, b int);
CREATE TABLE
plruby_test=# create or replace function tt(abort bool) returns bool as '
plruby_test'# transaction do |txn|
plruby_test'# PL.exec("insert into tu values (1, 2)")
plruby_test'# transaction do |txn1|
plruby_test'# PL.exec("insert into tu values (3, 4)")
plruby_test'# txn1.abort
plruby_test'# end
plruby_test'# PL.exec("insert into tu values (5, 6)")
plruby_test'# txn.abort if abort
plruby_test'# end
plruby_test'# abort
plruby_test'# ' language 'plruby';
CREATE FUNCTION
plruby_test=#
plruby_test=# select tt(true);
tt
----
t
(1 row)
plruby_test=# select * from tu;
a | b
---+---
(0 rows)
plruby_test=# select tt(false);
tt
----
f
(1 row)
plruby_test=# select * from tu;
a | b
---+---
1 | 2
5 | 6
(2 rows)
plruby_test=#
== Function returning SET (SFRM Materialize)
The return type must be declared as SETOF
The function must call ((%yield%)) to return rows or return a String which
must be a valid SELECT statement
For example to concatenate 2 rows create the function
plruby_test=# CREATE FUNCTION tu(varchar) RETURNS setof record
plruby_test-# AS '
plruby_test'# size = PL.column_name(args[0]).size
plruby_test'# res = nil
plruby_test'# PL::Plan.new("select * from #{args[0]}",
plruby_test'# "block" => 50).each do |row|
plruby_test'# if res.nil?
plruby_test'# res = row.values
plruby_test'# else
plruby_test'# res.concat row.values
plruby_test'# yield res
plruby_test'# res = nil
plruby_test'# end
plruby_test'# end
plruby_test'# if res
plruby_test'# res.concat Array.new(size)
plruby_test'# yield res
plruby_test'# end
plruby_test'# ' language 'plruby';
CREATE FUNCTION
plruby_test=#
plruby_test=# select * from tt;
a | b
---+----
1 | 2
3 | 4
5 | 6
7 | 8
9 | 10
(5 rows)
plruby_test=# select * from tu('tt') as tbl(a int, b int, c int, d int);
a | b | c | d
---+----+---+---
1 | 2 | 3 | 4
5 | 6 | 7 | 8
9 | 10 | |
(3 rows)
plruby_test=#
== Function returning SET (ExprMultiResult)
The return type must be declared as SETOF
The function is called until it returns nil
The method PL#context and PL#context= give the possibility to store information
between the call
For example
plruby_test=# create or replace function vv(int) returns setof int as '
plruby_test'# i = PL.context || 0
plruby_test'# if i >= args[0]
plruby_test'# nil
plruby_test'# else
plruby_test'# PL.context = i + 1
plruby_test'# end
plruby_test'# ' language plruby;
CREATE FUNCTION
plruby_test=#
plruby_test=# select * from uu;
b
---
2
(1 row)
plruby_test=#
plruby_test=# select *,vv(3) from uu;
b | vv
---+----
2 | 1
2 | 2
2 | 3
(3 rows)
plruby_test=#
== Trigger procedures in PL Ruby
Trigger procedures are defined in Postgres as functions without
arguments and a return type of trigger. In PL/Ruby the procedure is
called with 4 arguments :
:new (hash, tainted)
an hash containing the values of the new table row on INSERT/UPDATE
actions, or empty on DELETE.
:old (hash, tainted)
an hash containing the values of the old table row on UPDATE/DELETE
actions, or empty on INSERT
:args (array, tainted, frozen)
An array of the arguments to the procedure as given in the CREATE
TRIGGER statement
:tg (hash, tainted, frozen)
The following keys are defined
:name
The name of the trigger from the CREATE TRIGGER statement.
:relname
The name of the relation who has fired the trigger
:relid
The object ID of the table that caused the trigger procedure to be invoked.
:relatts
An array containing the name of the tables field.
:when
The constant ((%PL::BEFORE%)), ((%PL::AFTER%)) or
((%PL::UNKNOWN%)) depending on the event of the trigger call.
:level
The constant ((%PL::ROW%)) or ((%PL::STATEMENT%))
depending on the event of the trigger call.
:op
The constant ((%PL::INSERT%)), ((%PL::UPDATE%)) or
((%PL::DELETE%)) depending on the event of the trigger call.
The return value from a trigger procedure is one of the constant
((%PL::OK%)) or ((%PL::SKIP%)), or an hash. If the
return value is ((%PL::OK%)), the normal operation
(INSERT/UPDATE/DELETE) that fired this trigger will take
place. Obviously, ((%PL::SKIP%)) tells the trigger manager to
silently suppress the operation. The hash tells
PL/Ruby to return a modified row to the trigger manager that will be
inserted instead of the one given in ((%new%)) (INSERT/UPDATE
only). Needless to say that all this is only meaningful when the
trigger is BEFORE and FOR EACH ROW.
Here's a little example trigger procedure that forces an integer
value in a table to keep track of the # of updates that are performed
on the row. For new row's inserted, the value is initialized to 0 and
then incremented on every update operation :
CREATE FUNCTION trigfunc_modcount() RETURNS TRIGGER AS '
case tg["op"]
when PL::INSERT
new[args[0]] = 0
when PL::UPDATE
new[args[0]] = old[args[0]] + 1
else
return PL::OK
end
new
' LANGUAGE 'plruby';
CREATE TABLE mytab (num int4, modcnt int4, descr text);
CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
FOR EACH ROW EXECUTE PROCEDURE trigfunc_modcount('modcnt');
A more complex example (extract from test_setup.sql in the distribution)
which use the global variable ((%$Plans%)) to store a prepared
plan
create function trig_pkey2_after() returns trigger as '
if ! $Plans.key?("plan_dta2_upd")
$Plans["plan_dta2_upd"] =
PL::Plan.new("update T_dta2
set ref1 = $3, ref2 = $4
where ref1 = $1 and ref2 = $2",
["int4", "varchar", "int4", "varchar" ]).save
$Plans["plan_dta2_del"] =
PL::Plan.new("delete from T_dta2
where ref1 = $1 and ref2 = $2",
["int4", "varchar"]).save
end
old_ref_follow = false
old_ref_delete = false
case tg["op"]
when PL::UPDATE
new["key2"] = new["key2"].upcase
old_ref_follow = (new["key1"] != old["key1"]) ||
(new["key2"] != old["key2"])
when PL::DELETE
old_ref_delete = true
end
if old_ref_follow
n = $Plans["plan_dta2_upd"].exec([old["key1"], old["key2"], new["key1"],
new["key2"]])
warn "updated #{n} entries in T_dta2 for new key in T_pkey2" if n != 0
end
if old_ref_delete
n = $Plans["plan_dta2_del"].exec([old["key1"], old["key2"]])
warn "deleted #{n} entries from T_dta2" if n != 0
end
PL::OK
' language 'plruby';
create trigger pkey2_after after update or delete on T_pkey2
for each row execute procedure
trig_pkey2_after();
== plruby_singleton_methods
Sometime it can be usefull to define methods (in pure Ruby) which can be
called from a PL/Ruby function or a PL/Ruby trigger.
In this case, you have 2 possibilities
* the "stupid" way (({:-) :-) :-)}))
just close the current definition of the function (or trigger) with a
(({end})) and define your singleton method without the final (({end}))
Here a small and useless example
plruby_test=# CREATE FUNCTION tutu() RETURNS int4 AS '
plruby_test'# toto(1, 3) + toto(4, 4)
plruby_test'# end
plruby_test'#
plruby_test'# def PLtemp.toto(a, b)
plruby_test'# a + b
plruby_test'# ' LANGUAGE 'plruby';
CREATE
plruby_test=# select tutu();
tutu
----
12
(1 row)
plruby_test=#
* create a table plruby_singleton_methods with the columns (name, args, body)
At load time, PL/Ruby look if it exist a table plruby_singleton_methods and if
found try, for each row, to define singleton methods with the template :
def PLtemp.#{name} (#{args})
#{body}
end
The previous example can be written (you have a more complete example in
test/plp/test_setup.sql)
plruby_test=# SELECT * FROM plruby_singleton_methods;
name|args|body
----+----+-----
toto|a, b|a + b
(1 row)
plruby_test=# CREATE FUNCTION tutu() RETURNS int4 AS '
plruby_test'# toto(1, 3) + toto(4, 4)
plruby_test'# ' LANGUAGE 'plruby';
CREATE
plruby_test=# select tutu();
tutu
----
12
(1 row)
plruby_test=#
* Another example, if PLRuby was compiled with --enable-conversion and it
exist a column with the name '***' then it can create a singleton method
from a PLRuby function
plruby_test=# select * from plruby_singleton_methods;
name | args | body
------+------+------
*** | |
(1 row)
plruby_test=# create function add_value(int, int) returns int as '
plruby_test'# args[0] + args[1]
plruby_test'# ' language 'plruby';
CREATE FUNCTION
plruby_test=#
plruby_test=# select add_value(10, 2);
add_value
-----------
12
(1 row)
plruby_test=#
plruby_test=# create function add_one(int) returns int as '
plruby_test'# add_value(args[0], 1)
plruby_test'# ' language 'plruby';
CREATE FUNCTION
plruby_test=#
plruby_test=# select add_one(11);
add_one
---------
12
(1 row)
plruby_test=#
== Conversion
If the conversions was not disabled (--disable-conversion), the following
conversions are made
PostgreSQL Ruby
---------- ----
OID Fixnum
INT2OID Fixnum
INT4OID Fixnum
INT8OID Fixnum (or Bignum)
FLOAT4OID Float
FLOAT8OID Float
CASHOID Float
NUMERICOID Float
BOOLOID true, false
ABSTIMEOID Time
RELTIMEOID Time
TIMEOID Time
TIMETZOID Time
TIMESTAMPOID Time
TIMESTAMPTZOID Time
DATEOID Time
INTERVALOID Time
TINTERVALOID Tinterval (new Ruby class)
BITOID BitString (new Ruby class)
VARBITOID BitString (new Ruby class)
INETOID NetAddr (new Ruby class)
CIDROID NetAddr (new Ruby class)
MACADDROID MacAddr (new Ruby class)
POINTOID Point (new Ruby class)
LSEGOID Segment (new Ruby class)
BOXOID Box (new Ruby class)
PATHOID Path (new Ruby class)
POLYGONOID Polygon (new Ruby class)
CIRCLEOID Circle (new Ruby class)
all others OID are converted to a String object
== Class and modules
=== Global
--- transaction {|txn| }
create a new transaction, yield an object ((%PL::Transaction%))
--- warn [level], message
Ruby interface to PostgreSQL elog()
Possible value for ((%level%)) are ((%NOTICE%)), ((%DEBUG%)) and ((%NOIND%))
Use ((%raise()%)) if you want to simulate ((%elog(ERROR, "...")%))
--- $Plans (hash, tainted)
can be used to store prepared plans.
=== module PL
general module
--- args_type
Return the type of the arguments given to the function
--- column_name(table)
Return the name of the columns for the table
--- column_type(table)
return the type of the columns for the table
--- context
Return the context (or nil) associated with a SETOF function
(ExprMultiResult)
--- context=
Set the context for a SETOF function (ExprMultiResult)
--- quote(string)
Duplicates all occurences of single quote and backslash
characters. It should be used when variables are used in the query
string given to spi_exec or spi_prepare (not for the value list on
execp).
--- result_name
Return the name of the columns for a function returning a SETOF
--- result_type
Return the type of the columns for a function returning a SETOF
or the type of the return value
--- result_size
Return the number of columns for a function returning a SETOF
--- result_description
Return the table description given to a function returning a SETOF
--- exec(string [, count [, type]])
--- spi_exec(string [, count [, type]])
Call parser/planner/optimizer/executor for query. The optional
((%count%)) value tells spi_exec the maximum number of rows to be
processed by the query.
:SELECT
If the query is a SELECT statement, an array is return (if count is
not specified or with a value > 1). Each element of this array is an
hash where the key is the column name.
If type is specified it can take the value
* "array" return for each column an array with the element
["name", "value", "type", "len", "typeid"]
* "hash" return for each column an hash with the keys
{"name", "value", "type", "len", "typeid"}
* "value" return all values
For example this procedure display all rows in the table pg_table.
CREATE FUNCTION pg_table_dis() RETURNS int4 AS '
res = PLruby.exec("select * from pg_class")
res.each do |x|
warn "======================"
x.each do |y, z|
warn "name = #{y} -- value = #{z}"
end
warn "======================"
end
return res.size
' LANGUAGE 'plruby';
A block can be specified, in this case a call to yield() will be
made.
If count is specified with the value 1, only the first row (or
FALSE if it fail) is returned as a hash. Here a little example :
CREATE FUNCTION pg_table_dis() RETURNS int4 AS '
PL.exec("select * from pg_class", 1) { |y, z|
warn "name = #{y} -- value = #{z}"
}
return 1
' LANGUAGE 'plruby';
Another example with count = 1
create table T_pkey1 (
skey1 int4,
skey2 varchar(20),
stxt varchar(40)
);
create function toto() returns bool as '
warn("=======")
PL.exec("select * from T_pkey1", 1, "hash") do |a|
warn(a.inspect)
end
warn("=======")
PL.exec("select * from T_pkey1", 1, "array") do |a|
warn(a.inspect)
end
warn("=======")
PL.exec("select * from T_pkey1", 1) do |a|
warn(a.inspect)
end
warn("=======")
return true
' language 'plruby';
plruby_test=# select toto();
NOTICE: =======
NOTICE: {"name"=>"skey1", "typeid"=>23, "type"=>"int4", "value"=>"12", "len"=>4}
NOTICE: {"name"=>"skey2", "typeid"=>1043, "type"=>"varchar", "value"=>"a", "len"=>20}
NOTICE: {"name"=>"stxt", "typeid"=>1043, "type"=>"varchar", "value"=>"b", "len"=>40}
NOTICE: =======
NOTICE: ["skey1", "12", "int4", 4, 23]
NOTICE: ["skey2", "a", "varchar", 20, 1043]
NOTICE: ["stxt", "b", "varchar", 40, 1043]
NOTICE: =======
NOTICE: ["skey1", "12"]
NOTICE: ["skey2", "a"]
NOTICE: ["stxt", "b"]
NOTICE: =======
toto
------
t
(1 row)
plruby_test=#
:SELECT INTO, INSERT, UPDATE, DELETE
return the number of rows insered, updated, deleted, ...
:UTILITY
return TRUE
--- prepare(string[, types])
--- spi_prepare(string[, types])
--- prepare(string, "types" => types, "count" => count, "output" => type, "tmp" => true)
Deprecated : See ((%PL::Plan::new%)) and ((%PL::Plan#save%))
Prepares AND SAVES a query plan for later execution. It is a bit
different from the C level SPI_prepare in that the plan is
automatically copied to the toplevel memory context.
If the query references arguments, the type names must be given as a
Ruby array of strings. The return value from prepare is a
((%PL::Plan%)) object to be used in subsequent calls to
((%PL::Plan#exec%)).
If the hash given has the keys ((%count%)), ((%output%)) these values
will be given to the subsequent calls to ((%each%))
=== class PL::Plan
class for prepared plan
--- initialize(string, "types" => types, "count" => count, "output" => type, "save" => false)
Prepares a query plan for later execution.
If the query references arguments, the type names must be given as a
Ruby array of strings.
If the hash given has the keys ((%output%)), ((%count%)) these values
will be given to the subsequent calls to ((%each%))
If ((%"save"%)) as a true value, the plan will be saved
--- exec(values, [count [, type]])
--- execp(values, [count [, type]])
--- exec("values" => values, "count" => count, "output" => type)
--- execp("values" => values, "count" => count, "output" => type)
Execute a prepared plan from ((%PL::PLan::new%)) with variable
substitution. The optional ((%count%)) value tells
((%PL::Plan#exec%)) the maximum number of rows to be processed by the
query.
If there was a typelist given to ((%PL::Plan::new%)), an array
of ((%values%)) of exactly the same length must be given to
((%PL::Plan#exec%)) as first argument. If the type list on
((%PL::Plan::new%)) was empty, this argument must be omitted.
If the query is a SELECT statement, the same as described for
((%PL#exec%)) happens for the loop-body and the variables for
the fields selected.
If type is specified it can take the values
* "array" return an array with the element ["name", "value", "type", "len", "typeid"]
* "hash" return an hash with the keys {"name", "value", "type", "len", "typeid"}
* "value" return an array with all values
Here's an example for a PL/Ruby function using a prepared plan :
CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
if ! $Plans.key?("plan")
# prepare the saved plan on the first call
$Plans["plan"] = PL::Plan.new("SELECT count(*) AS cnt FROM t1
WHERE num >= $1 AND num <= $2",
["int4", "int4"]).save
end
n = $Plans["plan"].exec([args[0], args[1]], 1)
n["cnt"]
' LANGUAGE 'plruby';
--- cursor(name = nil, "values" => values, "output" => type)
Create a new object PL::Cursor
If output is specified it can take the values
* "array" return an array with the element ["name", "value", "type", "len", "typeid"]
* "hash" return an hash with the keys {"name", "value", "type", "len", "typeid"}
* "value" return an array with all values
If there was a typelist given to ((%PL::Plan::new%)), an array
of ((%values%)) of exactly the same length must be given to
((%PL::Plan#cursor%))
--- each(values, [count [, type ]]) { ... }
--- fetch(values, [count [, type ]]) { ... }
--- each("values" => values, "count" => count, "output" => type) { ... }
--- fetch("values" => values, "count" => count, "output" => type) { ... }
Same then #exec but a call to SPI_cursor_open(), SPI_cursor_fetch() is made.
Can be used only with a block and a SELECT statement
create function toto() returns bool as '
plan = PL::Plan.new("select * from T_pkey1")
warn "=====> ALL"
plan.each do |x|
warn(x.inspect)
end
warn "=====> FIRST 2"
plan.each("count" => 2) do |x|
warn(x.inspect)
end
return true
' language 'plruby';
plruby_test=# select * from T_pkey1;
skey1 | skey2 | stxt
-------+-------+------
12 | a | b
24 | c | d
36 | e | f
(3 rows)
plruby_test=#
plruby_test=# select toto();
NOTICE: =====> ALL
NOTICE: {"skey1"=>"12", "skey2"=>"a", "stxt"=>"b"}
NOTICE: {"skey1"=>"24", "skey2"=>"c", "stxt"=>"d"}
NOTICE: {"skey1"=>"36", "skey2"=>"e", "stxt"=>"f"}
NOTICE: =====> FIRST 2
NOTICE: {"skey1"=>"12", "skey2"=>"a", "stxt"=>"b"}
NOTICE: {"skey1"=>"24", "skey2"=>"c", "stxt"=>"d"}
toto
------
t
(1 row)
plruby_test=#
--- release
Release a query plan
--- save
Save a query plan for later execution. The plan is copied to the
toplevel memory context.
=== class PL::Cursor
A cursor is created with the method PL::Plan#cursor
--- close
Closes a cursor
--- each {|row| ... }
Iterate over all rows (forward)
--- fetch(count = 1)
--- row(count = 1)
Fetches some rows from a cursor
if count > 0 fetch forward else backward
--- move(count)
Move a cursor : if count > 0 move forward else backward
--- reverse_each {|row| ... }
Iterate over all rows (backward)
--- rewind
Positions the cursor at the beginning of the table
=== class PL::Transaction
a transaction is created with the global function ((%transaction()%)). Only
available with PostgreSQL >= 8.0
--- abort
Abort the transaction
--- commit
Commit the transaction
=== class BitString
The class BitString implement the PostgreSQL type ((|bit|))
and ((|bit varying|))
The modules Comparable and Enumerable are included
--- from_string(string, length = strlen(string))
Convert a ((|String|)) to a ((|BitString|))
--- <=>(other)
comparison function for 2 ((|BitString|)) objects
All bits are considered and additional zero bits may make one string
smaller/larger than the other, even if their zero-padded values would
be the same.
--- +(other)
Concatenate ((|self|)) and ((|other|))
--- &(other)
AND operator
--- |(other)
OR operator
--- ^(other)
XOR operator
--- ~
NOT operator
--- <<(lshft)
LEFT SHIFT operator
--- >>(rshft)
RIGHT SHIFT operator
--- [](*args)
Element reference with the same syntax that for a ((|String|)) object
Return a ((|BitString|)) or a ((|Fixnum|)) 0, 1
bitstring[fixnum]
bitstring[fixnum, fixnum]
bitstring[range]
bitstring[regexp]
bitstring[regexp, fixnum]
bitstring[string]
bitstring[other_bitstring]
--- []=(*args)
Element assignment with the same syntax that for a ((|String|)) object
bitstring[fixnum] = fixnum
bitstring[fixnum] = string_or_bitstring
bitstring[fixnum, fixnum] = string_or_bitstring
bitstring[range] = string_or_bitstring
bitstring[regexp] = string_or_bitstring
bitstring[regexp, fixnum] = string_or_bitstring
bitstring[other_str] = string_or_bitstring
--- concat(other)
append ((|other|)) to ((|self|))
--- each
iterate other each bit
--- include?(other)
return ((|true|)) if ((|other|)) is included in ((|self|))
--- index(other)
return the position of ((|other|)) in ((|self|))
return ((|nil|)) if ((|other|)) is not included in ((|self|))
--- initialize(init, nbits = -1)
create a new ((|BitString|)) object with ((|nbits|)) bits
((|init|)) can be a ((|Fixnum|)) or a ((|String|))
For a ((|String|)) the first character can be 'x', 'X' for and
hexadecimal representation, or 'b', 'B' for a binary representation.
The default is a binary representation
--- length
return the length of ((|self|)) in bits
--- octet_length
return the length of ((|self|)) in octets
--- push(other)
append ((|other|)) to ((|self|))
--- to_i
convert ((|self|)) to a ((|Fixnum|))
--- to_s
convert ((|self|)) to a ((|String|))
=== class NetAddr
The class NetAddr implement the PostgreSQL type ((|inet|))
and ((|cidr|))
The module Comparable is included
--- from_string(string, cidr = false)
Convert a ((|String|)) to a ((|NetAddr|))
--- <=>(other)
comparison function for 2 ((|NetAddr|)) objects
comparison is first on the common bits of the network part, then on
the length of the network part, and then on the whole unmasked address.
--- abbrev
return the abbreviated display format as a ((|String|)) object
--- broadcast
return the broadcast address from the network
--- contain?(other)
return true if ((|other|)) is included in ((|self|))
--- contain_or_equal?(other)
return true if ((|other|)) is included in ((|self|)), or equal
--- contained?(other)
return true if ((|self|)) is included in ((|other|))
--- contained_or_equal?(other)
return true if ((|self|)) is included in ((|other|)), or equal
--- family
return the String "AF_INET" or "AF_INET6"
--- first
return the first address in the network
--- host
extract the IP address and return it as a ((|String|))
--- hostmask
return the host mask for network
--- initialize(string, cidr = false)
create a ((|NetAddr|)) from a ((|String|))
--- last
return the last address in the network
--- masklen
return the length of the netmask
--- netmask
return the netmask for the network
--- network
return the network part of the address
--- set_masklen(len)
return a new ((|NetAddr|)) with netmask length ((|len|))
--- to_s
return the string representation of the address
=== class MacAddr
The MacAddr implement the PostgreSQL type ((|macaddr|))
The module Comparable is included
--- from_string(string, cidr = false)
Convert a ((|String|)) to a ((|MacAddr|))
--- <=>(other)
comparison function for 2 ((|MacAddr|)) objects
--- initialize(string)
create a ((|MacAddr|)) from a ((|String|))
--- to_s
return the string representation of the MAC address
--- truncate
return a new object with the last 3 bytes set to zero
=== class Tinterval
The Tinterval implement the PostgreSQL type ((|tinterval|))
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Tinterval|))
--- high
return a ((|Time|)) which is the high value of the interval
--- high=(time)
set the high value for the interval
--- initialize(low, high)
create a ((|Tinterval|)) with the 2 ((|Time|)) objects
((|low|)) and ((|high|))
--- low
return a ((|Time|)) which is the low value of the interval
--- low=(time)
set the low value for the interval
--- to_s
return the string representation of the object
=== class Box
The Box implement the PostgreSQL type ((|box|))
The module Comparable is included
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Box|)) object
--- +(point)
translate (right, up) ((|self|))
--- -(point)
translate (left, down) ((|self|))
--- *(point)
scale and rotate ((|self|))
--- /(point)
scale and rotate ((|self|))
--- ===(other)
return true if the 2 boxes ((|self|)) and ((|other|)) are identical
--- <=>(other)
comparison operator for 2 Box based on the area of the 2 objects, i.e.
self.area <=> box.area
--- above?(other)
return true if ((|self|)) is above ((|other|))
--- area
return the area of the Box
--- below?(other)
return true if ((|self|)) is below ((|other|))
--- center
return the center point of the Box
--- closest(other)
closest point to ((|other|))
((|other|)) can be a Point, or Segment
--- contain?(other)
return true if ((|self|)) contain ((|other|))
--- contained?(other)
return true if ((|self|)) is contained by ((|other|))
--- diagonal
return a line Segment which happens to be the
positive-slope diagonal of Box
--- height
return the height of the Box (vertical magnitude)
--- in?(other)
return true if ((|self|)) is contained by ((|other|))
--- initialize(*args)
create a new Box object
((|args|)) can be 2 Point objects (low, high) or 4 Float objects
(low.x, low.y, high.x, high.y)
--- intersection(other)
returns the overlapping portion of two boxes,
or ((|nil|)) if they do not intersect.
--- intersect?(segment)
returns true if the Segment ((|segment|))
intersect with the Box
Segment completely inside box counts as intersection.
If you want only segments crossing box boundaries,
try converting Box to Path first.
--- left?(other)
return true if ((|self|)) is strictly left of ((|other|))
--- overlap?(other)
return true if ((|self|)) overlap ((|other|))
--- overleft?(other)
return true if the right edge of ((|self|)) is to the left of
the right edge of ((|other|))
--- overright?(other)
return true if the left edge of ((|self|)) is to the right of
the left edge of ((|other|))
--- right?(other)
return true if ((|self|)) is strictly right of ((|other|))
--- same?(other)
return true if the 2 boxes ((|self|)) and ((|other|)) are identical
--- to_circle
convert a Box to a Circle
--- to_point
return the center Point of the Box
--- to_polygon
convert a Box to a Polygon
--- to_segment
return a line Segment which happens to be the
positive-slope diagonal of Box
--- width
return the width of the Box (horizontal magnitude)
=== class Path
The Path implement the PostgreSQL type ((|path|))
The module Comparable is included
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Path|))
--- <<(path)
concatenate the two paths (only if they are both open)
--- +(point)
translate (right, up) ((|self|))
--- -(point)
translate (left, down) ((|self|))
--- *(point)
scale and rotate ((|self|))
--- /(point)
scale and rotate ((|self|))
--- <=>(other)
comparison function based on the path cardinality, i.e.
self.npoints <=> other.npoints
--- close
make a closed path
--- closed?
return true if ((|self|)) is a closed path
--- concat(path)
concatenate the two paths (only if they are both open)
--- initialize(points, closed = false)
create a new Path object from the Array of Point ((|points|))
--- length
return the length of ((|self|))
--- npoints
return the path cardinality
--- open
make an open path
--- to_polygon
convert ((|self|)) to a Polygon object
=== class Point
The Point implement the PostgreSQL type ((|point|))
The module Comparable is included
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Point|))
--- +(point)
translate (right, up) ((|self|))
--- -(point)
translate (left, down) ((|self|))
--- *(point)
scale and rotate ((|self|))
--- /(point)
scale and rotate ((|self|))
--- [](indice)
return the coordinate
((|indice|)) can have the value 0 or 1
--- []=(indice, value)
set the coordinate
((|indice|)) can have the value 0 or 1
--- ==(other)
return true if ((|self|)) and ((|other|)) are the same,
i.e. self.x == other.x && self.y == other.y
--- above?(other)
return true if ((|self|)) is above ((|other|)),
i.e. self.y > other.y
--- below?(other)
return true if ((|self|)) is below ((|other|)),
i.e. self.y < other.y
--- contained?(other)
return true if ((|self|)) is contained in ((|other|))
((|other|)) can be Point, Polygon or a Circle object
--- horizontal?(other)
return true if ((|self|)) and ((|other|)) are horizontal,
i.e. self.y == other.y
--- in?(other)
return true if ((|self|)) is contained in ((|other|))
((|other|)) can be Point, Polygon or a Circle object
--- initialize(x, y)
create a Point with the 2 Float object (x, y)
--- left?(other)
return true if ((|self|)) is at the left of ((|other|)),
i.e. self.x < other.x
--- on?(other)
return true if ((|self|)) is on ((|other|))
((|other|)) can be Point, Segment, Box or Path object
--- right?(other)
return true if ((|self|)) is at the right of ((|other|)),
i.e. self.x > other.x
--- vertical?(other)
return true if ((|self|)) and ((|other|)) are vertical,
i.e. self.x == other.x
--- x
return ((|x|)) for ((|self|))
--- x=(value)
set the ((|x|)) value for ((|self|))
--- y
return ((|y|)) for ((|self|))
--- y=(value)
set the ((|y|)) value for ((|self|))
=== class Segment
The Segment implement the PostgreSQL type ((|lseg|))
The module Comparable is included
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Segment|))
--- <=>(other)
comparison function for the 2 segments, returns
0 if self[0] == other[0] && self[1] == other[1]
1 if distance(self[0], self[1]) > distance(other[0], other[1])
-1 if distance(self[0], self[1]) < distance(other[0], other[1])
--- center
return the center of the segment
--- closest(other)
closest point to other
((|other|)) can be a Point, Segment or Box
With a point, take the closest endpoint
if the point is left, right, above, or below the segment, otherwise
find the intersection point of the segment and its perpendicular through
the point.
--- horizontal?
returns true if ((|self|)) is a horizontal Segment
--- initialize(point0, point1)
create a Segment from the 2 Point p0, p1
--- intersect?(other)
returns true if ((|self|)) and ((|other|)) intersect
--- intersection(other)
returns the Point where the 2 Segment ((|self|)) and ((|other|))
intersect or nil
--- length
return the length of ((|self|)), i.e. the distnace between the 2 points
--- on?(other)
return true if ((|self|)) is on ((|other|))
((|other|)) can be a Segment, or a Box object
--- parallel?(other)
returns true if the 2 Segment ((|self|)) and ((|other|))
are parallel
--- perpendicular?(other)
returns true if ((|self|)) is perpendicular to ((|other|))
--- to_point
conversion function to a Point, return the center of the segment
--- vertical?
returns true if ((|self|)) is a vertical Segment
=== class Polygon
The Polygon implement the PostgreSQL type ((|polygon|))
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Polygon|))
--- ==(other)
return true if ((|self|)) is the same as ((|other|)), i.e. all
the points are the same
--- center
return the center of ((|self|)), i.e. create a circle and return its
center
--- contain?(other)
return true if ((|self|)) contains ((|other|))
((|other|)) can be a Point or a Polygon
--- contained?(other)
return true if ((|self|)) is contained in ((|other|)) by determining
if ((|self|)) bounding box is contained by ((|other|))'s bounding box.
--- in?(other)
return true if ((|self|)) is contained in ((|other|)) by determining
if ((|self|)) bounding box is contained by ((|other|))'s bounding box.
--- initialize(points, closed = false)
create a new Polygon object from the Array of Point ((|points|))
--- left?(other)
return true if ((|self|)) is strictly left of ((|other|)), i.e.
the right most point of ((|self|)) is left of the left
most point of ((|other|))
--- overleft?(other)
return true if ((|self|)) is overlapping or left of ((|other|)),
i.e. the left most point of ((|self|)) is left of the right
most point of ((|other|))
--- overright?(other)
return true if ((|self|)) is overlapping or right of ((|other|)),
i.e. the right most point of ((|self|)) is right of the left
most point of ((|other|))
--- overlap?(other)
return true if ((|self|)) and ((|other|)) overlap by determining if
their bounding boxes overlap.
--- npoints
return the number of points in ((|self|))
--- right?(other)
return true if ((|self|)) is strictly right of ((|other|)), i.e.
the left most point of ((|self|)) is right of the left
most point of ((|other|))
--- same?(other)
return true if ((|self|)) is the same as ((|other|)), i.e. all
the points are the same
--- to_box
convert ((|self|)) to a Box
--- to_circle
convert ((|self|)) to a Circle
--- to_path
convert ((|self|)) to a Path
--- to_point
convert ((|self|)) to a Point by returning its center
=== class Circle
The Circle implement the PostgreSQL type ((|circle|))
The module Comparable is included
--- from_string(string)
Convert a ((|String|)) (PostgreSQL representation)
to a ((|Circle|))
--- +(point)
translate (right, up) ((|self|))
--- -(point)
translate (left, down) ((|self|))
--- *(point)
scale and rotate ((|self|))
--- /(point)
scale and rotate ((|self|))
--- <=>(other)
comparison function based on area,
i.e. self.area <=> other.area
--- area
return the area
--- above?(other)
return true if ((|self|)) is entirely above ((|other|))
--- below?(other)
return true if ((|self|)) is entirely below ((|other|))
--- contain?(other)
return true if ((|self|)) contain ((|other|))
--- contained?(other)
return true if ((|self|)) is contained in ((|other|))
--- diameter
return the diameter
--- initialize(center, radius)
create a Circle object with ((|center|)) and ((|radius|))
((|center|)) can be a Point or an Array [x, y]
--- overlap?(other)
return true if ((|self|)) overlap ((|other|))
--- overleft?(other)
return true if the right edge of ((|self|)) is to the left of
the right edge of ((|other|))
--- left?(other)
return true if ((|self|)) is strictly left of ((|other|))
--- overright?(other)
return true if the left edge of ((|self|)) is to the right of
the left edge of ((|other|))
--- radius
return the radius
--- right?(other)
return true if ((|self|)) is strictly right of ((|other|))
--- same?(other)
return true if ((|self|)) is the same than ((|other|)), i.e.
self.center == other.center && self.radius == other.radius
--- to_box
convert ((|self|)) to a Box
--- to_point
convert ((|self|)) to a Point by returning its center
--- to_polygon(npts)
convert ((|self|)) to a Polygon with ((|npts|)) Points
=end
Jump to Line
Something went wrong with that request. Please try again.