apr::table.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.IP "\(bu" 4
\&\f(CW\*(C`APR::Const::OVERLAP_TABLES_MERGE\*(C'\fR
.Sp
Start with table \f(CW$table\fR:
.Sp
.Vb 4
\&  foo => "one"
\&  foo => "two"
\&  foo => "three"
\&  bar => "beer"
.Ve
.Sp
as in the previous example, now compress it using
\&\f(CW\*(C`APR::Const::OVERLAP_TABLES_MERGE\*(C'\fR:
.Sp
.Vb 1
\&  $table\->compress(APR::Const::OVERLAP_TABLES_MERGE);
.Ve
.Sp
Now table \f(CW$table\fR contains:
.Sp
.Vb 2
\&  foo => "one, two, three"
\&  bar => "beer"
.Ve
.Sp
All the values for the same key were merged into one value.
.ie n .Sh """copy"""
.el .Sh "\f(CWcopy\fP"
.IX Subsection "copy"
Create a new table and copy another table into it.
.PP
.Vb 1
\&  $table_copy = $table\->copy($p);
.Ve
.ie n .IP "obj: $table\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "obj: \f(CW$table\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "obj: $table ( APR::Table object )"
The table to copy.
.ie n .IP "arg1: $p\fR ( \f(CW""APR::Pool object"" )" 4
.el .IP "arg1: \f(CW$p\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "arg1: $p ( APR::Pool object )"
The pool to allocate the new table out of.
.ie n .IP "ret: $table_copy\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "ret: \f(CW$table_copy\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "ret: $table_copy ( APR::Table object )"
A copy of the table passed in.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .Sh """do"""
.el .Sh "\f(CWdo\fP"
.IX Subsection "do"
Iterate over all the elements of the table, invoking provided
subroutine for each element.  The subroutine gets passed as argument,
a key-value pair.
.PP
.Vb 1
\&  $table\->do(sub {...}, @filter);
.Ve
.ie n .IP "obj: $table\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "obj: \f(CW$table\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "obj: $table ( APR::Table object )"
The table to operate on.
.ie n .IP "arg1: $sub ( \s-1CODE\s0 ref/string )" 4
.el .IP "arg1: \f(CW$sub\fR ( \s-1CODE\s0 ref/string )" 4
.IX Item "arg1: $sub ( CODE ref/string )"
A subroutine reference or name to be called on each item in the table.
The subroutine can abort the iteration by returning 0 and should
always return 1 otherwise.
.ie n .IP "opt arg3: @filter ( \s-1ARRAY\s0 )" 4
.el .IP "opt arg3: \f(CW@filter\fR ( \s-1ARRAY\s0 )" 4
.IX Item "opt arg3: @filter ( ARRAY )"
If passed, only keys matching one of the entries in f\f(CW@filter\fR will be
processed.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
Examples:
.IP "\(bu" 4
This filter simply prints out the key/value pairs and counts how many
pairs did it see.
.Sp
.Vb 3
\&  use constant TABLE_SIZE => 20;
\&  our $filter_count;
\&  my $table = APR::Table::make($r\->pool, TABLE_SIZE);
\&  
\&  # populate the table with ascii data
\&  for (1..TABLE_SIZE) {
\&      $table\->set(chr($_+97), $_);
\&  }
\&  
\&  $filter_count = 0;
\&  $table\->do("my_filter");
\&  print "Counted $filter_count elements";
\&  
\&  sub my_filter {
\&      my ($key, $value) = @_;
\&      warn "$key => $value\en";
\&      $filter_count++;
\&      return 1;
\&  }
.Ve
.Sp
Notice that \f(CW\*(C`my_filter\*(C'\fR always returns 1, ensuring that \f(CW\*(C`do()\*(C'\fR will
pass all the key/value pairs.
.IP "\(bu" 4
This filter is similar to the one from the previous example, but this
time it decides to abort the filtering after seeing half of the table,
by returning 0 when this happens.
.Sp
.Vb 5
\&  sub my_filter {
\&      my ($key, $value) = @_;
\&      $filter_count++;
\&      return $filter_count == int(TABLE_SIZE)/2 ? 0 : 1;
\&  }
.Ve
.ie n .Sh """get"""
.el .Sh "\f(CWget\fP"
.IX Subsection "get"
Get the value(s) associated with a given key.  After this call, the
data is still in the table.
.PP
.Vb 2
\&  $val = $table\->get($key);
\&  @val = $table\->get($key);
.Ve
.ie n .IP "obj: $table\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "obj: \f(CW$table\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "obj: $table ( APR::Table object )"
The table to search for the key.
.ie n .IP "arg1: $key ( string )" 4
.el .IP "arg1: \f(CW$key\fR ( string )" 4
.IX Item "arg1: $key ( string )"
The key to search for.
.ie n .IP "ret: $val\fR or \f(CW@val" 4
.el .IP "ret: \f(CW$val\fR or \f(CW@val\fR" 4
.IX Item "ret: $val or @val"
In the scalar context the first matching value returned (the oldest in
the table, if there is more than one value). If nothing matches
\&\f(CW\*(C`undef\*(C'\fR is returned.
.Sp
In the list context the whole table is traversed and all matching
values are returned. An empty list is returned if nothing matches.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .Sh """make"""
.el .Sh "\f(CWmake\fP"
.IX Subsection "make"
Make a new table.
.PP
.Vb 1
\&  $table = APR::Table::make($p, $nelts);
.Ve
.ie n .IP "obj: $p\fR ( \f(CW""APR::Pool object"" )" 4
.el .IP "obj: \f(CW$p\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "obj: $p ( APR::Pool object )"
The pool to allocate the pool out of.
.ie n .IP "arg1: $nelts ( integer )" 4
.el .IP "arg1: \f(CW$nelts\fR ( integer )" 4
.IX Item "arg1: $nelts ( integer )"
The number of elements in the initial table. At least 1 or more. If 0
is passed \s-1APR\s0 will still allocate 1.
.ie n .IP "ret: $table\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "ret: \f(CW$table\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "ret: $table ( APR::Table object )"
The new table.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
This table can only store text data.
.ie n .Sh """merge"""
.el .Sh "\f(CWmerge\fP"
.IX Subsection "merge"
Add data to a table by merging the value with data that has already
been stored using \*(L", \*(R" as a separator:
.PP
.Vb 1
\&  $table\->merge($key, $val);
.Ve
.ie n .IP "obj: $table\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "obj: \f(CW$table\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "obj: $table ( APR::Table object )"
The table to search for the data.
.ie n .IP "arg1: $key ( string )" 4
.el .IP "arg1: \f(CW$key\fR ( string )" 4
.IX Item "arg1: $key ( string )"
The key to merge data for.
.ie n .IP "arg2: $val ( string )" 4
.el .IP "arg2: \f(CW$val\fR ( string )" 4
.IX Item "arg2: $val ( string )"
The data to add.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
If the key is not found, then this function acts like
\&\f(CW\*(C`add()\*(C'\fR.
.PP
If there is more than one value for the same key, only the first (the
oldest) value gets merged.
.PP
Examples:
.IP "\(bu" 4
Start with a pair:
.Sp
.Vb 1
\&  merge => "1"
.Ve
.Sp
and merge \*(L"a\*(R" to the value:
.Sp
.Vb 3
\&  $table\->set(  merge => \*(Aq1\*(Aq);
\&  $table\->merge(merge => \*(Aqa\*(Aq);
\&  $val = $table\->get(\*(Aqmerge\*(Aq);
.Ve
.Sp
Result:
.Sp
.Vb 1
\&  $val == "1, a";
.Ve
.IP "\(bu" 4
Start with a multivalued pair:
.Sp
.Vb 2
\&  merge => "1"
\&  merge => "2"
.Ve
.Sp
and merge \*(L"a\*(R" to the first value;
.Sp
.Vb 4
\&  $table\->set(  merge => \*(Aq1\*(Aq);
\&  $table\->add(  merge => \*(Aq2\*(Aq);
\&  $table\->merge(merge => \*(Aqa\*(Aq);
\&  @val = $table\->get(\*(Aqmerge\*(Aq);
.Ve
.Sp
Result:
.Sp
.Vb 2
\&  $val[0] == "1, a";
\&  $val[1] == "2";
.Ve
.Sp
Only the first value for the same key is affected.
.IP "\(bu" 4
Have no entry and merge \*(L"a\*(R";
.Sp
.Vb 2
\&  $table\->merge(miss => \*(Aqa\*(Aq);
\&  $val = $table\->get(\*(Aqmiss\*(Aq);
.Ve
.Sp
Result:
.Sp
.Vb 1
\&  $val == "a";
.Ve
.ie n .Sh """overlap"""
.el .Sh "\f(CWoverlap\fP"
.IX Subsection "overlap"
For each key/value pair in \f(CW$table_b\fR, add the data to
\&\f(CW$table_a\fR. The definition of \f(CW$flags\fR explains how \f(CW$flags\fR define
the overlapping method.
.PP
.Vb 1
\&  $table_a\->overlap($table_b, $flags);
.Ve
.ie n .IP "obj: $table_a\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "obj: \f(CW$table_a\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "obj: $table_a ( APR::Table object )"
The table to add the data to.
.ie n .IP "arg1: $table_b\fR ( \f(CW""APR::Table object"" )" 4
.el .IP "arg1: \f(CW$table_b\fR ( \f(CWAPR::Table object\fR )" 4
.IX Item "arg1: $table_b ( APR::Table object )"
The table to iterate over, adding its data to table \f(CW$table_a\fR
.ie n .IP "arg2: $flags ( integer )" 4
.el .IP "arg2: \f(CW$flags\fR ( integer )" 4
.IX Item "arg2: $flags ( integer )"
How to add the table to table \f(CW$table_a\fR.
.Sp
When \f(CW$flags\fR == \f(CW\*(C`APR::Const::OVERLAP_TABLES_SET\*(C'\fR, if another element
already exists with the same key, this will over-write the old data.
.Sp
When \f(CW$flags\fR == \f(CW\*(C`APR::Const::OVERLAP_TABLES_MERGE\*(C'\fR, the key/value pair
from \f(CW$table_b\fR is added, regardless of whether there is another
element with the same key in \f(CW$table_a\fR.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
Access the constants via:
.PP
.Vb 1
\&  use APR::Const \-compile qw(:table);
.Ve
.PP
or an explicit:
.PP
.Vb 1
\&  use APR::Const \-compile qw(OVERLAP_TABLES_SET OVERLAP_TABLES_MERGE);
.Ve
.PP
This function is highly optimized, and uses less memory and \s-1CPU\s0 cycles
than a function that just loops through table \f(CW$table_b\fR calling
other functions.
.PP
Conceptually, \f(CW\*(C`overlap()\*(C'\fR does this:
.PP
.Vb 3
\&  apr_array_header_t *barr = apr_table_elts(b);
\&  apr_table_entry_t *belt = (apr_table_entry_t *)barr\-E<gt>elts;
\&  int i;
\&  
\&  for (i = 0; i < barr\->nelts; ++i) {
\&      if (flags & APR_OVERLAP_TABLES_MERGE) {
\&          apr_table_mergen(a, belt[i].key, belt[i].val);
\&      }
\&      else {
\&          apr_table_setn(a, belt[i].key, belt[i].val);
\&      }
\&  }
.Ve
.PP
Except that it is more efficient (less space and cpu-time) especially
when \f(CW$table_b\fR has many elements.
.PP
Notice the assumptions on the keys and values in \f(CW$table_b\fR \*(-- they
must be in an ancestor of \f(CW$table_a\fR's pool.  In practice \f(CW$table_b\fR
and \f(CW$table_a\fR are usually from the same pool.
.PP
Examples:
.IP "\(bu" 4
\&\f(CW\*(C`APR::Const::OVERLAP_TABLES_SET\*(C'\fR
.Sp
Start with table \f(CW$base\fR:
.Sp
.Vb 3
\&  foo => "one"
\&  foo => "two"
\&  bar => "beer"