/usr/share/doc/stilts/sun256/jel-colref.html is in stilts-doc 3.1.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>Referencing Column Values</title>
</head>
<body>
<hr>
<a href="jel-paramref.html">Next</a> <a href="jel.html">Previous</a> <a href="jel.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jel-paramref.html">Referencing Parameter Values</a><br>
<b>Up: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<b>Previous: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<hr>
<h3><a name="jel-colref">10.1 Referencing Column Values</a></h3>
<p>To create a useful expression which can be evaluated for each row
in a table, you will have to refer to cells in different columns of that row.
You can do this in three ways:
<dl>
<dt><strong>By Name</strong></dt>
<dd>The Name of the column may be used if it is unique (no other column in
the table has the same name) and if it has a suitable form.
This means that it must have the form of a Java variable - basically
starting with a letter and continuing with
letters, numbers, underscores and currency symbols.
In particular it cannot contain spaces, commas, parentheses etc.
<p>As a special case, if an expression contains just a single column name,
rather than some more complicated expression,
then any column name may be used, even one containing non-alphanumeric
characters.
</p>
<p>Column names are treated case-insensitively.
</p>
</dd>
<dt><strong>By $ID</strong></dt>
<dd>The "$ID"
identifier of the column may always be used to refer to it;
this is a useful fallback if the column name isn't suitable for
some reason (for instance it contains spaces or is not unique).
This is just a "$" sign followed by the column index -
the first column is $1.
</dd>
<dt><strong>By ucd$ specifier</strong></dt>
<dd>If the column has a
<a href="http://www.ivoa.net/Documents/latest/UCD.html">Unified Content Descriptor</a>
(this will usually only be the case for VOTable or possibly FITS format
tables) you can refer to it using an identifier of the form
"<code>ucd$<ucd-spec></code>". Depending on the version of
UCD scheme used, UCDs can contain various punctuation marks such
as underscores, semicolons and dots; for the purpose of this syntax
these should all be represented as underscores ("<code>_</code>").
So to identify a column which has the UCD "<code>phot.mag;em.opt.R</code>",
you should use the identifier "<code>ucd$phot_mag_em_opt_r</code>".
Matching is not case-sensitive. Futhermore, a trailing underscore
acts as a wildcard, so that the above column could also be referenced
using the identifier "<code>ucd$phot_mag_</code>". If multiple
columns have UCDs which match the given identifer, the first one
will be used.
<p>Note that the same syntax can be used for referencing table
parameters (see the <a href="jel-paramref.html">next section</a>);
columns take preference so if a column and a parameter both match
the requested UCD, the column value will be used.
</p>
</dd>
<dt><strong>By utype$ specifier</strong></dt>
<dd>If the column has a <b>Utype</b>
(this will usually only be the case for VOTable or possibly FITS format
tables) you can refer to it using an identifier of the form
"<code>utype$<utype-spec></code>".
Utypes can contain various punctuation marks such as colons and dots;
for the purpose of this syntax
these should all be represented as underscores ("<code>_</code>").
So to identify a column which has the Utype
"<code>ssa:Access.Format</code>",
you should use the identifier
"<code>utype$ssa_Access_Format</code>".
Matching is not case-sensitive.
If multiple columns have Utypes which match the given identifier,
the first one will be used.
<p>Note that the same syntax can be used for referencing table
parameters (see the <a href="jel-paramref.html">next section</a>);
columns take preference so if a column and a parameter both match
the requested Utype, the column value will be used.
</p>
</dd>
<dt><strong>With the Object$ prefix</strong></dt>
<dd>If a column is referenced with the prefix "<code>Object$</code>"
before its identifier
(e.g. "<code>Object$BMAG</code>" for a column named <code>BMAG</code>)
the result will be the column value as a java Object.
Without that prefix, numeric columns are evaluated as java primitives.
In most cases, you <em>don't want to do this</em>,
since it means that you can't use the value in arithmetic expressions.
However, if you need the value to be passed to a
(possibly user-defined) method,
and you need that method to be invoked even when the value is null,
you have to do it like this. Null-valued primitives
otherwise cause expression evaluation to abort.
</dd>
</dl>
</p>
<p>There is also a special column:
<dl>
<dt><strong><code>$index</code></strong></dt>
<dd>The value of this is the current row number (the first row is 1).
You can alternatively use the form
<strong><code>$0</code></strong>.
(The form <strong><code>index</code></strong> is also permitted,
but deprecated).
Note that this value is a <code>long</code> (8-byte integer);
when using it in certain expressions you may find it necessary to convert
it to an <code>int</code> (4-byte integer) using the
<code>toInteger()</code> function.
</dd>
</dl>
</p>
<p>The value of the variables so referenced will be a primitive
(boolean, byte, short, char, int, long, float, double) if the
column contains one of the corresponding types. Otherwise it will
be an Object of the type held by the column, for instance a String.
In practice this means: you can write the name of a column, and it will
evaluate to the numeric (or string) value that that column contains
in each row. You can then use this in normal algebraic expressions
such as "<code>B_MAG-U_MAG</code>" as you'd expect.
</p>
<hr><a href="jel-paramref.html">Next</a> <a href="jel.html">Previous</a> <a href="jel.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jel-paramref.html">Referencing Parameter Values</a><br>
<b>Up: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<b>Previous: </b><a href="jel.html">Algebraic Expression Syntax</a><br>
<hr><i>STILTS - Starlink Tables Infrastructure Library Tool Set<br>Starlink User Note256<br>STILTS web page:
<a href="http://www.starlink.ac.uk/stilts/">http://www.starlink.ac.uk/stilts/</a><br>Author email:
<a href="mailto:m.b.taylor@bristol.ac.uk">m.b.taylor@bristol.ac.uk</a><br>Mailing list:
<a href="mailto:topcat-user@jiscmail.ac.uk">topcat-user@jiscmail.ac.uk</a><br></i></body>
</html>
|