documentation for special table lookups (subnet or pattern index types)

script-reference/types.rst

@@ -1114,6 +1114,48 @@ See the :zeek:keyword:`for` statement for information on how to iterate over
 the elements in a table.
 
 
+Special lookups
+^^^^^^^^^^^^^^^
+
+Zeek supports two forms of special table lookups. The first is for tables
+with an index type of :zeek:type:`subnet`. When indexed with an
+:zeek:type:`addr` value, these tables produce the yield associated with
+the closest (narrowest) subnet. For example:
+
+.. code-block:: zeek
+
+    global st: table[subnet] of count;
+    st[1.2.3.4/24] = 5;
+    st[1.2.3.4/29] = 9;
+    print st[1.2.3.4], st[1.2.3.251];
+
+will print ``9, 5``. Attempting to look up an address that doesn't match
+any of the subnet indices results in a run-time error.
+
+In addition, you can index tables that have an index type of
+:zeek:type:`pattern` using a :zeek:type:`string` value. This lookup returns
+a (possibly empty) :zeek:type:`vector` of yield values corresponding to
+each of the patterns that match. For example:
+
+.. code-block:: zeek
+
+    global pt: table[pattern] of count;
+    pt[/foo/] = 1;
+    pt[/bar/] = 2;
+    pt[/(foo|bletch)/] = 3;
+    print pt["foo"];
+
+will print either ``[1, 3]`` or ``[3, 1]`` (the order can vary).
+Indexing with a string that matches only one pattern still returns a
+(one-element) :zeek:type:`vector`, and indexing with a string that no
+pattern matches returns an empty :zeek:type:`vector`.
+
+Note that these pattern matches are all *exact*: the pattern must match
+the entire string. If you want the pattern to match if it's *anywhere*
+in the string, you can use the usual regular expression operators such
+as ``/.*foo.*/``.
+
+
 Additional operations
 ^^^^^^^^^^^^^^^^^^^^^