001package votorola.a.count; // Copyright 2012, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE. 002 003 004/** The exclusive relation of one person (the person) to another (the anchor) in the 005 * votespace of a poll, such as voter or candidate. The following diagram shows the 006 * immediate cast relations of a particular anchor. The anchor has a {@linkplain #SELF 007 * self} (s), two {@linkplain #VOTER voters} (v), two {@linkplain #CO_VOTER co-voters} 008 * (o), and a {@linkplain #CANDIDATE candidate} (c):<pre> 009 * 010 * ( ) ( ) ( ) 011 * \ | / 012 * \ | / 013 * ( ) ( ) \ | / 014 * ( ) \ | \|/ 015 * \ \ | (v) 016 * \ \ | | 017 * \ \| | 018 * \ (v) | ( ) ( ) 019 * ( )-----( ) \ | | / | 020 * \ \ | | / | vote flow 021 * \ \ | | / V 022 * \ \ | |/ 023 * ( ) \ \| (o)-----( ) 024 * | ( )-----(o) (s) / 025 * ( ) | \ | / ( ) 026 * \ | \ | / | ( ) ( )( ) 027 * \| \ | / | / | / 028 * ( ) ( ) \|/ |/ |/ 029 * ( ) | \ ( ) (c) ( )----( ) ( ) 030 * \ | ( ) \ | \ ( ) / ( ) | 031 * \ | / \ | \ | / \ | ( ) 032 * \ | / \| \ | / \ | / 033 * \|/ ( ) \|/ ( ) \|/ 034 * ( ) \ ( )---( ) ( ) | ( ) ( ) 035 * \ / \ / | / 036 * \ / \ / |/ 037 * ( ) ( )------( )----( ) 038 * \ / 039 * \ / 040 * ( )---( )</pre> 041 * 042 * The scope may be limited to immediate votespace, as shown above, in which case the 043 * relation (if any) may be calculated soley from the votes of the two persons. 044 * Alternatively the scope may be extended upstream and downstream from the anchor, as 045 * illustrated in the extended relations below.<pre> 046 * 047 * (v) (v) (v) 048 * \ | / 049 * \ | / 050 * (v) (v) \ | / 051 * ( ) \ | \|/ 052 * \ \ | (v) 053 * \ \ | | 054 * \ \| | 055 * \ (v) | ( ) ( ) 056 * ( )-----( ) \ | | / | 057 * \ \ | | / | vote flow 058 * \ \ | | / V 059 * \ \ | |/ 060 * ( ) \ \| (o)-----( ) 061 * | ( )-----(o) (s) / 062 * ( ) | \ | / ( ) 063 * \ | \ | / | ( ) ( )( ) 064 * \| \ | / | / | / 065 * ( ) ( ) \|/ |/ |/ 066 * ( ) | \ ( ) (c) ( )----( ) ( ) 067 * \ | ( ) \ | \ ( ) / ( ) | 068 * \ | / \ | \ | / \ | ( ) 069 * \ | / \| \ | / \ | / 070 * \|/ ( ) \|/ ( ) \|/ 071 * ( ) \ (c)---(c) ( ) | ( ) ( ) 072 * \ / \ / | / 073 * \ / \ / |/ 074 * (c) (c)------( )----( ) 075 * \ / 076 * \ / 077 * (c)---(c)</pre> 078 * 079 * If the anchor (s) is moved into the cycle at the base of the tree, then {@linkplain 080 * #CO_BASE base co-candidate} relations (b) also appear. The base co-candidates include 081 * both <a href='../../../../../d/theory.xht#base-candidate' target='_top'>root 082 * candidates</a> (left and right) and <a href='../../../../../d/theory.xht#cycle' 083 * target='_top'>cyclers</a> (center).<pre> 084 * 085 * \ \ | | / 086 * \ \ | |/ 087 * ( ) \ \| (v)-----(v) 088 * | (v)-----(v) (v) / 089 * ( ) | \ | / (v) 090 * \ | \ | / | (v) ( )( ) 091 * \| \ | / | / | / 092 * ( ) ( ) \|/ |/ |/ 093 * ( ) | \ ( ) (v) (v)----(v) ( ) 094 * \ | ( ) \ | \ (v) / ( ) | 095 * \ | / \ | \ | / \ | ( ) 096 * \ | / \| \ | / \ | / 097 * \|/ ( ) \|/ ( ) \|/ 098 * (b) \ (b)---(s) (o) | ( ) (b) 099 * \ / \ / | / 100 * \ / \ / |/ 101 * (b) (b)------(o)----( ) 102 * \ / 103 * \ / 104 * (b)---(b) 105 * 106 * 107 * <---</pre> 108 * 109 * These cast relations are exclusive in the sense that <em>at most</em> one relation 110 * applies for a person at any given moment. The person is never both a voter and a 111 * candidate to the anchor even in a tight cycle, but is rather a base co-candidate. A 112 * tight cycle is illustrated below, where the cast edges go left and right between the 113 * person (b) and the anchor (s).<pre> 114 * 115 * (v) (v) (o) 116 * (v) | / (o) / 117 * \ | / | / 118 * \|/ --> |/ 119 * (s)=======(b)---(o) 120 * <--</pre> 121 * 122 * Exclusivity is useful in visual styling, as for example in <a 123 * href='../diff/DiffKey.html#ord'>difference ordering</a> and {@linkplain 124 * votorola.s.gwt.mediawiki.ShadowLight shadow lighting}. 125 */ 126public enum XCastRelation 127{ 128 129 130 /** The person and the anchor are the same. The symbol for this relation is 's'. 131 */ 132 SELF( 's' ), 133 134 135 /** The anchor is a recipient of the person's vote and the person is not a base 136 * candidate. The person is a voter to the anchor. The symbol for this relation is 137 * 'v'. 138 * 139 * @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base 140 * candidate</a> 141 */ // per INLDOC 142 VOTER( 'v' ), 143 144 145 /** Another candidate is the <em>direct</em> recipient of both the person's vote and 146 * the anchor's vote. The person is a co-voter to the anchor (and vice versa). The 147 * symbol for this relation is 'o'. 148 */ 149 CO_VOTER( 'o' ), 150 151 152 /** Both the person and the anchor are base candidates. The person is a base 153 * co-candidate to the anchor (and vice versa). The symbol for this relation is 'b'. 154 * 155 * @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base 156 * candidate</a> 157 */ // per INLDOC 158 CO_BASE( 'b' ), 159 160 161 /** The person is a recipient of the anchor's vote and the anchor is not a base 162 * candidate. The person is a candidate to the anchor. The symbol for this relation 163 * is 'c'. 164 * 165 * @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base 166 * candidate</a> 167 */ // per INLDOC 168 CANDIDATE( 'c' ), 169 170 171 /** The style symbol 'u' for the unknown cast relation. 172 */ 173 UNKNOWN( 'u' ); 174 175 176 177 private XCastRelation( char _symbol ) { symbol = _symbol; } 178 179 180 181 // -------------------------------------------------------------------------------- 182 183 184 /** Returns the character symbol of the relation. 185 */ 186 public char symbol() { return symbol; } 187 188 189 private final char symbol; 190 191 192}