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

TIE Interface

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

Copyright

695       mod_perl 2.0 and its core modules are copyrighted under The Apache
696       Software License, Version 2.0.
697

Authors

699       The mod_perl development team and numerous contributors.
700
701
702
703perl v5.36.0                      2023-01-19          docs::api::APR::Table(3)