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

TIE Interface

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

Copyright

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

Authors

700       The mod_perl development team and numerous contributors.
701
702
703
704perl v5.34.0                      2022-02-02          docs::api::APR::Table(3)