Editing Module:Val/units/doc (section)

=== Sorting ===
{{details|topic=sorting |Help:sorting }}
{{details|topic=scaling |Template:Ntsh}}

Val's sorting scale factor is for comparison to other Val units that might be sorted with it. 

Where [[Help:Sorting|Sorting]] is done on the wiki, it is done in [[Help:table#Sortable tables|sortable tables]].  
Val entries in a sortable table will need a fourth field sorting flag.  It can be a number, an equation, or an <kbd>SI</kbd>, but it flags the same function: a wikitable sorting "scale".  

To display the sort key use {{para|debug|yes}}.  For example

*<code><nowiki>{{val|999|u=uV|debug=yes}}</nowiki></code> → <span class="nowrap"><span style="border:1px solid;display:inline;" data-sort-value="6996998999999999999♠">999&nbsp;µV</span></span>
*<code><nowiki>{{val|99|u=V|debug=yes}}</nowiki></code>   → <span class="nowrap"><span style="border:1px solid;display:inline;" data-sort-value="7001990000000000000♠>99&nbsp;V</span></span>
*<code><nowiki>{{val|1|u=kV|debug=yes}}</nowiki></code>   → <span class="nowrap"><span style="border:1px solid;display:inline;" data-sort-value="7003100000000000000♠>1&nbsp;kV</span></span>

==== Scale ====

For scaling a unit to sort properly, you need to pick a number for a sorting factor. 
There are numerous examples at [[Template:Val/list]]. A [[system of units]] will have its base units, for example 1 bit; then the scale for sorting a kilobyte unit is then 8000 (eight bits per byte, times a kilo, or thousand). Or a year scale is seconds so that all ''times'' sort by seconds, which is a base unit.  In general the scale shows to be "base unit" of the same type times the "SI prefix", and if it's not that simple, then the unit system's number has associated a number to it, such as Avogadro's number.  

For example, the following defines a unit with code <code>billion</code>, symbol <code>billion</code>, link [[1,000,000,000]], and scale <code>1e9</code> ({{val|1|e=9}}).  After the following entry is saved to the database
<pre>
billion            billion          1,000,000,000          1e9
</pre>
{{tlx|val|2|u{{=}}billion}} would start sorting after {{tlx|val|98.7|e{{=}}3}}.

==== SI flag ====
{{common metric prefixes}}
SI is used because it scales Val expressions automatically, and it is a clean indicator that the unit will sort properly. It correctly scales any SI prefix for sorting, but not other unit codes.

For SI the unit symbol will not accept HTML, but will accept &mu;. HTML is not accepted at this time because in order to validate the entry, the unit code must differ from the unit symbol by exactly one valid [[SI prefix]]. If there is no difference, or too much difference, it is an invalid definition for sorting purposes.  The exception is for the Greek letter &mu;: if you used a character input application to "install" the Greek letter <code>&mu;</code> in your symbol, for your "easy to type" unit code, {{key|u}}, these two are not a character mismatch.

All unit entries that use SI will have the same base unit as the symbol at Val/units, but they will display properly at Val/list.

For example, kilo is a thousand, but you're defining km2 for kilometers squared, and need HTML.  You can't use SI with HTML, so use 1000*1000, or 1000000 in the sorting field. Use [[e notation|1e-6]] or 0.000001 or 1/100000 instead. 

If the unit you are maintaining has SI prefixes and they are all likely to be sorted in a table, add up to twelve entries, one for each common SI unit.  Some of these, like ''Meter'' in the example, may have their own article, but usually all go to the base unit's pagename.  Here is how ''meter'' is defined.

<pre>
m     [[Metre|m]]         SI
cm    [[Centimetre|m]]    SI
dam   [[Decametre|m]]     SI
dm    [[Decimetre|m]]     SI
hm    [[Hectometre|m]]    SI
km    [[Kilometre|m]]     SI
Mm    [[Megametre|m]]     SI
mm    [[Millimetre|m]]    SI
um    [[Micrometre|µm]]   1/1000000
µm    [[Micrometre|m]]    SI
nm    [[Nanometre|m]]     SI
pm    [[Picometre|m]]     SI
</pre>

The information that was in the unit symbol is now fully specified in, and exhibited at, the unit code.  <code>SI</code> specifies that the unit's symbol has been transformed from a symbol to a string for use in string comparison that will finally result in calculating a sorting factor.  It conveniently uses the idea that the unit code is often equal to the symbol, especially with SI units.  The field definitions are sacrificed for a simplicity in the user presentation, user calculation, and user entry.

In the other format, the following defines three unit codes for volts, V for sorting.  V is the base unit with the SI prefix removed. A unit code defined in this manner will have its sort key scaled by the software according to the SI prefix produced by the difference between the unit code and unit symbol.
:<code>kV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Kilovolt&nbsp;&nbsp;&nbsp;&nbsp;SI</code>
:<code>µV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;SI</code>
:<code>uV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;SI</code>
Now {{tlx|val|1|u{{=}}kV}} will sort after {{tlx|val|999|u{{=}}V}} without having to resort to using a number, and with the clean representation at Val/list.

The symbol column shows "V" for each, but it is not the symbol—it is the base unit after removing the SI prefix so convert can work out what is intended to be the prefix. The following would give identical results:
:<code>kV&nbsp;&nbsp;&nbsp;kV&nbsp;&nbsp;&nbsp;Kilovolt&nbsp;&nbsp;&nbsp;&nbsp;1e3</code>
:<code>µV&nbsp;&nbsp;&nbsp;µV&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;1e-6</code>
:<code>uV&nbsp;&nbsp;&nbsp;µV&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;1e-6</code>
As you can see, without "SI", you define both the symbol, and the scale.  You define the symbol with HTML or the Greek letter or other symbol, and you define the scale with a number or an equation. When "SI" is used, convert just does the right thing for the symbol and scale.