APR::Table(3pm)

1docs::api::APR::Table(3U)ser Contributed Perl Documentatidooncs::api::APR::Table(3)
2
3
4

NAME

6       APR::Table - Perl API for manipulating APR opaque string-content tables
7

Synopsis

9         use APR::Table ();
10
11         $table = APR::Table::make($pool, $nelts);
12         $table_copy = $table->copy($pool);
13
14         $table->clear();
15
16         $table->set($key => $val);
17         $table->unset($key);
18         $table->add($key, $val);
19
20         $val = $table->get($key);
21         @val = $table->get($key);
22
23         $table->merge($key => $val);
24
25         use APR::Const -compile qw(:table);
26         $table_overlay = $table_base->overlay($table_overlay, $pool);
27         $table_overlay->compress(APR::Const::OVERLAP_TABLES_MERGE);
28
29         $table_a->overlap($table_b, APR::Const::OVERLAP_TABLES_SET);
30
31         $table->do(sub {print "key $_[0], value $_[1]\n"}, @valid_keys);
32
33         #Tied Interface
34         $value = $table->{$key};
35         $table->{$key} = $value;
36         print "got it" if exists $table->{$key};
37
38         foreach my $key (keys %{$table}) {
39             print "$key = $table->{$key}\n";
40         }
41

Description

43       "APR::Table" allows its users to manipulate opaque string-content
44       tables.
45
46       On the C level the "opaque string-content" means: you can put in
47       '\0'-terminated strings and whatever you put in your get out.
48
49       On the Perl level that means that we convert scalars into strings and
50       store those strings. Any special information that was in the Perl
51       scalar is not stored. So for example if a scalar was marked as utf8,
52       tainted or tied, that information is not stored. When you get the data
53       back as a Perl scalar you get only the string.
54
55       The table's structure is somewhat similar to the Perl's hash structure,
56       but allows multiple values for the same key.  An access to the records
57       stored in the table always requires a key.
58
59       The key-value pairs are stored in the order they are added.
60
61       The keys are case-insensitive.
62
63       However as of the current implementation if more than value for the
64       same key is requested, the whole table is lineary searched, which is
65       very inefficient unless the table is very small.
66
67       "APR::Table" provides a TIE Interface.
68
69       See apr/include/apr_tables.h in ASF's apr project for low level
70       details.
71

API

73       "APR::Table" provides the following functions and/or methods:
74
75       "add"
76
77       Add data to a table, regardless of whether there is another element
78       with the same key.
79
80         $table->add($key, $val);
81
82       obj: $table ( "APR::Table object" )
83           The table to add to.
84
85       arg1: $key ( string )
86           The key to use.
87
88       arg2: $val ( string )
89           The value to add.
90
91       ret: no return value
92       since: 2.0.00
93
94       When adding data, this function makes a copy of both the key and the
95       value.
96
97       "clear"
98
99       Delete all of the elements from a table.
100
101         $table->clear();
102
103       obj: $table ( "APR::Table object" )
104           The table to clear.
105
106       ret: no return value
107       since: 2.0.00
108
109       "compress"
110
111       Eliminate redundant entries in a table by either overwriting or merging
112       duplicates:
113
114         $table->compress($flags);
115
116       obj: $table ( "APR::Table object" )
117           The table to compress.
118
119       arg1: $flags ("APR::Const constant")
120             APR::Const::OVERLAP_TABLES_MERGE -- to merge
121             APR::Const::OVERLAP_TABLES_SET   -- to overwrite
122
123       ret: no return value
124       since: 2.0.00
125
126       Converts multi-valued keys in $table into single-valued keys.  This
127       function takes duplicate table entries and flattens them into a single
128       entry.  The flattening behavior is controlled by the (mandatory) $flags
129       argument.
130
131       When $flags == "APR::Const::OVERLAP_TABLES_SET", each key will be set
132       to the last value seen for that key.  For example, given key/value
133       pairs 'foo => bar' and 'foo => baz', 'foo' would have a final value of
134       'baz' after compression -- the 'bar' value would be lost.
135
136       When $flags == "APR::Const::OVERLAP_TABLES_MERGE", multiple values for
137       the same key are flattened into a comma-separated list.  Given
138       key/value pairs 'foo => bar' and 'foo => baz', 'foo' would have a final
139       value of 'bar, baz' after compression.
140
141       Access the constants via:
142
143         use APR::Const -compile qw(:table);
144
145       or an explicit:
146
147         use APR::Const -compile qw(OVERLAP_TABLES_SET OVERLAP_TABLES_MERGE);
148
149       "compress()" combined with "overlay()" does the same thing as "over‐
150       lap()".
151
152       Examples:
153
154       * "APR::Const::OVERLAP_TABLES_SET"
155           Start with table $table:
156
157             foo => "one"
158             foo => "two"
159             foo => "three"
160             bar => "beer"
161
162           which is done by:
163
164             use APR::Const    -compile => ':table';
165             my $table = APR::Table::make($r->pool, TABLE_SIZE);
166
167             $table->set(bar => 'beer');
168             $table->set(foo => 'one');
169             $table->add(foo => 'two');
170             $table->add(foo => 'three');
171
172           Now compress it using "APR::Const::OVERLAP_TABLES_SET":
173
174             $table->compress(APR::Const::OVERLAP_TABLES_SET);
175
176           Now table $table contains:
177
178             foo => "three"
179             bar => "beer"
180
181           The value three for the key foo, that was added last, took over the
182           other values.
183
184       * "APR::Const::OVERLAP_TABLES_MERGE"
185           Start with table $table:
186
187             foo => "one"
188             foo => "two"
189             foo => "three"
190             bar => "beer"
191
192           as in the previous example, now compress it using
193           "APR::Const::OVERLAP_TABLES_MERGE":
194
195             $table->compress(APR::Const::OVERLAP_TABLES_MERGE);
196
197           Now table $table contains:
198
199             foo => "one, two, three"
200             bar => "beer"
201
202           All the values for the same key were merged into one value.
203
204       "copy"
205
206       Create a new table and copy another table into it.
207
208         $table_copy = $table->copy($p);
209
210       obj: $table ( "APR::Table object" )
211           The table to copy.
212
213       arg1: $p ( "APR::Pool object" )
214           The pool to allocate the new table out of.
215
216       ret: $table_copy ( "APR::Table object" )
217           A copy of the table passed in.
218
219       since: 2.0.00
220
221       "do"
222
223       Iterate over all the elements of the table, invoking provided subrou‐
224       tine for each element.  The subroutine gets passed as argument, a key-
225       value pair.
226
227         $table->do(sub {...}, @filter);
228
229       obj: $table ( "APR::Table object" )
230           The table to operate on.
231
232       arg1: $sub ( CODE ref/string )
233           A subroutine reference or name to be called on each item in the ta‐
234           ble.  The subroutine can abort the iteration by returning 0 and
235           should always return 1 otherwise.
236
237       opt arg3: @filter ( ARRAY )
238           If passed, only keys matching one of the entries in f@filter will
239           be processed.
240
241       ret: no return value
242       since: 2.0.00
243
244       Examples:
245
246       ·   This filter simply prints out the key/value pairs and counts how
247           many pairs did it see.
248
249             use constant TABLE_SIZE => 20;
250             our $filter_count;
251             my $table = APR::Table::make($r->pool, TABLE_SIZE);
252
253             # populate the table with ascii data
254             for (1..TABLE_SIZE) {
255                 $table->set(chr($_+97), $_);
256             }
257
258             $filter_count = 0;
259             $table->do("my_filter");
260             print "Counted $filter_count elements";
261
262             sub my_filter {
263                 my ($key, $value) = @_;
264                 warn "$key => $value\n";
265                 $filter_count++;
266                 return 1;
267             }
268
269           Notice that "my_filter" always returns 1, ensuring that "do()" will
270           pass all the key/value pairs.
271
272       ·   This filter is similar to the one from the previous example, but
273           this time it decides to abort the filtering after seeing half of
274           the table, by returning 0 when this happens.
275
276             sub my_filter {
277                 my ($key, $value) = @_;
278                 $filter_count++;
279                 return $filter_count == int(TABLE_SIZE)/2 ? 0 : 1;
280             }
281
282       "get"
283
284       Get the value(s) associated with a given key.  After this call, the
285       data is still in the table.
286
287         $val = $table->get($key);
288         @val = $table->get($key);
289
290       obj: $table ( "APR::Table object" )
291           The table to search for the key.
292
293       arg1: $key ( string )
294           The key to search for.
295
296       ret: $val or @val
297           In the scalar context the first matching value returned (the oldest
298           in the table, if there is more than one value). If nothing matches
299           "undef" is returned.
300
301           In the list context the whole table is traversed and all matching
302           values are returned. An empty list is returned if nothing matches.
303
304       since: 2.0.00
305
306       "make"
307
308       Make a new table.
309
310         $table = APR::Table::make($p, $nelts);
311
312       obj: $p ( "APR::Pool object" )
313           The pool to allocate the pool out of.
314
315       arg1: $nelts ( integer )
316           The number of elements in the initial table. At least 1 or more. If
317           0 is passed APR will still allocate 1.
318
319       ret: $table ( "APR::Table object" )
320           The new table.
321
322       since: 2.0.00
323
324       This table can only store text data.
325
326       "merge"
327
328       Add data to a table by merging the value with data that has already
329       been stored using ", " as a separator:
330
331         $table->merge($key, $val);
332
333       obj: $table ( "APR::Table object" )
334           The table to search for the data.
335
336       arg1: $key ( string )
337           The key to merge data for.
338
339       arg2: $val ( string )
340           The data to add.
341
342       ret: no return value
343       since: 2.0.00
344
345       If the key is not found, then this function acts like "add()".
346
347       If there is more than one value for the same key, only the first (the
348       oldest) value gets merged.
349
350       Examples:
351
352       ·   Start with a pair:
353
354             merge => "1"
355
356           and merge "a" to the value:
357
358             $table->set(  merge => '1');
359             $table->merge(merge => 'a');
360             $val = $table->get('merge');
361
362           Result:
363
364             $val == "1, a";
365
366       ·   Start with a multivalued pair:
367
368             merge => "1"
369             merge => "2"
370
371           and merge "a" to the first value;
372
373             $table->set(  merge => '1');
374             $table->add(  merge => '2');
375             $table->merge(merge => 'a');
376             @val = $table->get('merge');
377
378           Result:
379
380             $val[0] == "1, a";
381             $val[1] == "2";
382
383           Only the first value for the same key is affected.
384
385       ·   Have no entry and merge "a";
386
387             $table->merge(miss => 'a');
388             $val = $table->get('miss');
389
390           Result:
391
392             $val == "a";
393
394       "overlap"
395
396       For each key/value pair in $table_b, add the data to $table_a. The def‐
397       inition of $flags explains how $flags define the overlapping method.
398
399         $table_a->overlap($table_b, $flags);
400
401       obj: $table_a ( "APR::Table object" )
402           The table to add the data to.
403
404       arg1: $table_b ( "APR::Table object" )
405           The table to iterate over, adding its data to table $table_a
406
407       arg2: $flags ( integer )
408           How to add the table to table $table_a.
409
410           When $flags == "APR::Const::OVERLAP_TABLES_SET", if another element
411           already exists with the same key, this will over-write the old
412           data.
413
414           When $flags == "APR::Const::OVERLAP_TABLES_MERGE", the key/value
415           pair from $table_b is added, regardless of whether there is another
416           element with the same key in $table_a.
417
418       ret: no return value
419       since: 2.0.00
420
421       Access the constants via:
422
423         use APR::Const -compile qw(:table);
424
425       or an explicit:
426
427         use APR::Const -compile qw(OVERLAP_TABLES_SET OVERLAP_TABLES_MERGE);
428
429       This function is highly optimized, and uses less memory and CPU cycles
430       than a function that just loops through table $table_b calling other
431       functions.
432
433       Conceptually, "overlap()" does this:
434
435         apr_array_header_t *barr = apr_table_elts(b);
436         apr_table_entry_t *belt = (apr_table_entry_t *)barr-E<gt>elts;
437         int i;
438
439         for (i = 0; i < barr->nelts; ++i) {
440             if (flags & APR_OVERLAP_TABLES_MERGE) {
441                 apr_table_mergen(a, belt[i].key, belt[i].val);
442             }
443             else {
444                 apr_table_setn(a, belt[i].key, belt[i].val);
445             }
446         }
447
448       Except that it is more efficient (less space and cpu-time) especially
449       when $table_b has many elements.
450
451       Notice the assumptions on the keys and values in $table_b -- they must
452       be in an ancestor of $table_a's pool.  In practice $table_b and $ta‐
453       ble_a are usually from the same pool.
454
455       Examples:
456
457       * "APR::Const::OVERLAP_TABLES_SET"
458           Start with table $base:
459
460             foo => "one"
461             foo => "two"
462             bar => "beer"
463
464           and table $add:
465
466             foo => "three"
467
468           which is done by:
469
470             use APR::Const    -compile => ':table';
471             my $base = APR::Table::make($r->pool, TABLE_SIZE);
472             my $add  = APR::Table::make($r->pool, TABLE_SIZE);
473
474             $base->set(bar => 'beer');
475             $base->set(foo => 'one');
476             $base->add(foo => 'two');
477
478             $add->set(foo => 'three');
479
480           Now overlap using "APR::Const::OVERLAP_TABLES_SET":
481
482             $base->overlap($add, APR::Const::OVERLAP_TABLES_SET);
483
484           Now table $add is unmodified and table $base contains:
485
486             foo => "three"
487             bar => "beer"
488
489           The value from table "add" has overwritten all previous values for
490           the same key both had (foo).  This is the same as doing "overlay()"
491           followed by "compress()" with "APR::Const::OVERLAP_TABLES_SET".
492
493       * "APR::Const::OVERLAP_TABLES_MERGE"
494           Start with table $base:
495
496             foo => "one"
497             foo => "two"
498
499           and table $add:
500
501             foo => "three"
502             bar => "beer"
503
504           which is done by:
505
506             use APR::Const    -compile => ':table';
507             my $base = APR::Table::make($r->pool, TABLE_SIZE);
508             my $add  = APR::Table::make($r->pool, TABLE_SIZE);
509
510             $base->set(foo => 'one');
511             $base->add(foo => 'two');
512
513             $add->set(foo => 'three');
514             $add->set(bar => 'beer');
515
516           Now overlap using "APR::Const::OVERLAP_TABLES_MERGE":
517
518             $base->overlap($add, APR::Const::OVERLAP_TABLES_MERGE);
519
520           Now table $add is unmodified and table $base contains:
521
522             foo => "one, two, three"
523             bar => "beer"
524
525           Values from both tables for the same key were merged into one
526           value. This is the same as doing "overlay()" followed by "com‐
527           press()" with "APR::Const::OVERLAP_TABLES_MERGE".
528
529       "overlay"
530
531       Merge two tables into one new table. The resulting table may have more
532       than one value for the same key.
533
534         $table = $table_base->overlay($table_overlay, $p);
535
536       obj: $table_base ( "APR::Table object" )
537           The table to add at the end of the new table.
538
539       arg1: $table_overlay ( "APR::Table object" )
540           The first table to put in the new table.
541
542       arg2: $p ( "APR::Pool object" )
543           The pool to use for the new table.
544
545       ret: $table ( "APR::Table object" )
546           A new table containing all of the data from the two passed in.
547
548       since: 2.0.00
549
550       Examples:
551
552       ·   Start with table $base:
553
554             foo => "one"
555             foo => "two"
556             bar => "beer"
557
558           and table $add:
559
560             foo => "three"
561
562           which is done by:
563
564             use APR::Const    -compile => ':table';
565             my $base = APR::Table::make($r->pool, TABLE_SIZE);
566             my $add  = APR::Table::make($r->pool, TABLE_SIZE);
567
568             $base->set(bar => 'beer');
569             $base->set(foo => 'one');
570             $base->add(foo => 'two');
571
572             $add->set(foo => 'three');
573
574           Now overlay using "APR::Const::OVERLAP_TABLES_SET":
575
576             my $overlay = $base->overlay($add, APR::Const::OVERLAP_TABLES_SET);
577
578           That resulted in a new table $overlay (tables "add" and $base are
579           unmodified) which contains:
580
581             foo => "one"
582             foo => "two"
583             foo => "three"
584             bar => "beer"
585
586       "set"
587
588       Add a key/value pair to a table, if another element already exists with
589       the same key, this will over-write the old data.
590
591         $table->set($key, $val);
592
593       obj: $table ( "APR::Table object" )
594           The table to add the data to.
595
596       arg1: $key ( string )
597           The key to use.
598
599       arg2: $val ( string )
600           The value to add.
601
602       ret: no return value
603       since: 2.0.00
604
605       When adding data, this function makes a copy of both the key and the
606       value.
607
608       "unset"
609
610       Remove data from the table.
611
612         $table->unset($key);
613
614       obj: $table ( "APR::Table object" )
615           The table to remove data from.
616
617       arg1: $key ( string )
618           The key of the data being removed.
619
620       ret: no return value
621       since: 2.0.00
622

TIE Interface

624       "APR::Table" also implements a tied interface, so you can work with the
625       $table object as a hash reference.
626
627       The following tied-hash function are supported: "FETCH", "STORE",
628       "DELETE", "CLEAR", "EXISTS", "FIRSTKEY", "NEXTKEY" and "DESTROY".
629
630       Note regarding the use of "values()". "APR::Table" can hold more than
631       one key-value pair sharing the same key, so when using a table through
632       the tied interface, the first entry found with the right key will be
633       used, completely disregarding possible other entries with the same key.
634       With Perl 5.8.0 and higher "values()" will correctly list values the
635       corresponding to the list generated by "keys()". That doesn't work with
636       Perl 5.6. Therefore to portably iterate over the key-value pairs, use
637       "each()" (which fully supports multivalued keys), or "APR::Table::do".
638
639       "EXISTS"
640
641         $ret = $table->EXISTS($key);
642
643       obj: $table ( "APR::Table object" )
644       arg1: $key ( string )
645       ret: $ret ( integer )
646           true or false
647
648       since: 2.0.00
649
650       "CLEAR"
651
652         $table->CLEAR();
653
654       obj: $table ( "APR::Table object" )
655       ret: no return value
656       since: 2.0.00
657
658       "STORE"
659
660         $table->STORE($key, $val);
661
662       obj: $table ( "APR::Table object" )
663       arg1: $key ( string )
664       arg2: $val ( string )
665       ret: no return value
666       since: 2.0.00
667
668       "DELETE"
669
670         $table->DELETE($key);
671
672       obj: $table ( "APR::Table object" )
673       arg1: $key ( string )
674       ret: no return value
675       since: 2.0.00
676
677       "FETCH"
678
679         $ret = $table->FETCH($key);
680
681       obj: $table ( "APR::Table object" )
682       arg1: $key ( string )
683       ret: $ret ( string )
684       since: 2.0.00
685
686       When iterating through the table's entries with "each()", "FETCH" will
687       return the current value of a multivalued key.  For example:
688
689         $table->add("a" => 1);
690         $table->add("b" => 2);
691         $table->add("a" => 3);
692
693         ($k, $v) = each %$table; # (a, 1)
694         print $table->{a};       # prints 1
695
696         ($k, $v) = each %$table; # (b, 2)
697         print $table->{a};       # prints 1
698
699         ($k, $v) = each %$table; # (a, 3)
700         print $table->{a};       # prints 3 !!!
701
702         ($k, $v) = each %$table; # (undef, undef)
703         print $table->{a};       # prints 1
704

Copyright

709       mod_perl 2.0 and its core modules are copyrighted under The Apache
710       Software License, Version 2.0.
711

Authors

713       The mod_perl development team and numerous contributors.
714
715
716
717perl v5.8.8                       2006-11-19          docs::api::APR::Table(3)