1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html > <head><title>Associative arrays</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="generator" content="TeX4ht (https://tug.org/tex4ht/)"> <meta name="originator" content="TeX4ht (https://tug.org/tex4ht/)"> <!-- html,2 --> <meta name="src" content="langref.tex"> <link rel="stylesheet" type="text/css" href="langref.css"> </head><body > <!--l. 2550--><div class="crosslinks"><p class="noindent">[<a href="langrefse8.html" >next</a>] [<a href="langrefse6.html" >prev</a>] [<a href="langrefse6.html#taillangrefse6.html" >prev-tail</a>] [<a href="#taillangrefse7.html">tail</a>] [<a href="langref.html#langrefse7.html" >up</a>] </p></div> <h3 class="sectionHead"><span class="titlemark">7 </span> <a id="x9-1140007"></a>Associative arrays</h3> <a id="dx9-114001"></a> <!--l. 2552--><p class="noindent" >Associative arrays are implemented as hash tables with a maximum size set at startup. Associative arrays are too large to be created dynamically for individual probe handler runs, so they must be declared as global. The basic operations for arrays are setting and looking up elements. These operations are expressed in awk syntax: the array name followed by an opening bracket ([), a comma-separated list of up to nine index index expressions, and a closing bracket (]). Each index expression may be a string or a number, as long as it is consistently typed throughout the script. <!--l. 2562--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.1 </span> <a id="x9-1150007.1"></a>Examples</h4> <!--l. 2564--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 2564--><p class="indent" > <pre class="verbatim" id="verbatim-101"> # Increment the named array slot: foo [4,"hello"] ++ # Update a statistic: processusage [uid(),execname()] ++ # Set a timestamp reference point: times [tid()] = get_cycles() # Compute a timestamp delta: delta = get_cycles() - times [tid()] </pre> <!--l. 2577--><p class="nopar" ></dd></dl> <!--l. 2580--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.2 </span> <a id="x9-1160007.2"></a>Types of values</h4> <!--l. 2582--><p class="noindent" >Array elements may be set to a number, a string, or an aggregate. The type must be consistent throughout the use of the array. The first assignment to the array defines the type of the elements. Unset array elements may be fetched and return a null value (zero or empty string) as appropriate, but they are not seen by a membership test. <!--l. 2590--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.3 </span> <a id="x9-1170007.3"></a>Array capacity</h4> <!--l. 2592--><p class="noindent" >Array sizes can be specified explicitly or allowed to default to the maximum size as defined by MAXMAPENTRIES. See Section <a href="langrefse1.html#x3-110001.6">1.6<!--tex4ht:ref: sub:SystemTap-safety --></a> for details on changing MAXMAPENTRIES. <!--l. 2596--><p class="noindent" >You can explicitly specify the size of an array as follows: <!--l. 2598--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 2598--><p class="indent" > <pre class="verbatim" id="verbatim-102"> global ARRAY[<size>] </pre> <!--l. 2601--><p class="nopar" ></dd></dl> <!--l. 2603--><p class="noindent" >If you do not specify the size parameter, then the array is created to hold MAXMAPENTRIES number of elements. <!--l. 2606--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.4 </span> <a id="x9-1180007.4"></a>Array wrapping</h4> <!--l. 2608--><p class="noindent" >Arrays may be wrapped using the percentage symbol (%) causing previously entered elements to be overwritten if more elements are inserted than the array can hold. This works for both regular and statistics typed arrays. <!--l. 2612--><p class="noindent" >You can mark arrays for wrapping as follows: <!--l. 2614--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 2614--><p class="indent" > <pre class="verbatim" id="verbatim-103"> global ARRAY1%[<size>], ARRAY2% </pre> <!--l. 2617--><p class="nopar" ></dd></dl> <!--l. 2620--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.5 </span> <a id="x9-1190007.5"></a>Iteration, foreach</h4> <a id="dx9-119001"></a> <!--l. 2622--><p class="noindent" >Like awk, SystemTap’s foreach creates a loop that iterates over key tuples of an array, not only values. The iteration may be sorted by any single key or a value by adding an extra plus symbol (+) or minus symbol (-) to the code or limited to only a few elements with the limit keyword. The following are examples. <!--l. 2628--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 2628--><p class="indent" > <pre class="verbatim" id="verbatim-104"> # Simple loop in arbitrary sequence: foreach ([a,b] in foo)     fuss_with(foo[a,b]) # Loop in increasing sequence of value: foreach ([a,b] in foo+) { ... } # Loop in decreasing sequence of first key: foreach ([a-,b] in foo) { ... } # Print the first 10 tuples and values in the array in decreasing sequence foreach (v = [i,j] in foo- limit 10)     printf("foo[%d,%s] = %d\n", i, j, v) </pre> <!--l. 2643--><p class="nopar" ></dd></dl> <!--l. 2645--><p class="noindent" >The <span class="cmtt-10">break </span>and <span class="cmtt-10">continue </span>statements also work inside foreach loops. Since arrays can be large but probe handlers must execute quickly, you should write scripts that exit iteration early, if possible. For simplicity, SystemTap forbids any modification of an array during iteration with a foreach. <!--l. 2650--><p class="noindent" >For a full description of <span class="cmtt-10">foreach </span>see subsection <a href="langrefse6.html#x8-1070006.6">6.6<!--tex4ht:ref: sub:foreach --></a>. <!--l. 2652--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">7.6 </span> <a id="x9-1200007.6"></a>Deletion</h4> <a id="dx9-120001"></a> <!--l. 2654--><p class="noindent" >The <span class="cmtt-10">delete </span>statement can either remove a single element by index from an array or clear an entire array at once. See subsection <a href="langrefse6.html#x8-1040006.3">6.3<!--tex4ht:ref: sub:delete --></a> for details and examples. <!--l. 2658--><div class="crosslinks"><p class="noindent">[<a href="langrefse8.html" >next</a>] [<a href="langrefse6.html" >prev</a>] [<a href="langrefse6.html#taillangrefse6.html" >prev-tail</a>] [<a href="langrefse7.html" >front</a>] [<a href="langref.html#langrefse7.html" >up</a>] </p></div> <!--l. 2658--><p class="noindent" ><a id="taillangrefse7.html"></a> </body></html>
|
