package 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.


/** The exclusive relation of one person (the person) to another (the anchor) in the
  * votespace of a poll, such as voter or candidate.  The following diagram shows the
  * immediate cast relations of a particular anchor.  The anchor has a {@linkplain #SELF
  * self} (s), two {@linkplain #VOTER voters} (v), two {@linkplain #CO_VOTER co-voters}
  * (o), and a {@linkplain #CANDIDATE candidate} (c):<pre>
  *
  *                         ( )  ( )  ( )
  *                           \   |   /
  *                            \  |  /
  *                   ( )  ( )  \ | /
  *               ( )   \   |    \|/
  *                 \    \  |    (v)
  *                  \    \ |     |
  *                   \    \|     |
  *                    \   (v)    |    ( )  ( )
  *            ( )-----( )   \    |     |   /           |
  *                      \    \   |     |  /            | vote flow
  *                       \    \  |     | /             V
  *                        \    \ |     |/
  *       ( )               \    \|    (o)-----( )
  *        |        ( )-----(o)  (s)   /
  *    ( ) |                  \   |   /    ( )
  *      \ |                   \  |  /      | ( )               ( )( )
  *       \|                    \ | /       | /                  | /
  *       ( )       ( )          \|/        |/                   |/
  *  ( )   |          \  ( )     (c)       ( )----( )           ( )
  *    \   |  ( )      \  |        \  ( )  /                ( )  |
  *     \  |  /         \ |         \  |  /                   \  | ( )
  *      \ | /           \|          \ | /                     \ | /
  *       \|/            ( )          \|/         ( )           \|/
  *       ( )              \    ( )---( )   ( )    | ( )        ( )
  *                         \   /       \   /      | /
  *                          \ /         \ /       |/
  *                          ( )         ( )------( )----( )
  *                            \         /
  *                             \       /
  *                             ( )---( )</pre>
  *
  * The scope may be limited to immediate votespace, as shown above, in which case the
  * relation (if any) may be calculated soley from the votes of the two persons.
  * Alternatively the scope may be extended upstream and downstream from the anchor, as
  * illustrated in the extended relations below.<pre>
  *
  *                          (v)  (v)  (v)
  *                            \   |   /
  *                             \  |  /
  *                    (v)  (v)  \ | /
  *                ( )   \   |    \|/
  *                  \    \  |    (v)
  *                   \    \ |     |
  *                    \    \|     |
  *                     \   (v)    |    ( )  ( )
  *             ( )-----( )   \    |     |   /           |
  *                       \    \   |     |  /            | vote flow
  *                        \    \  |     | /             V
  *                         \    \ |     |/
  *       ( )                \    \|    (o)-----( )
  *        |         ( )-----(o)  (s)   /
  *    ( ) |                   \   |   /    ( )
  *      \ |                    \  |  /      | ( )                ( )( )
  *       \|                     \ | /       | /                   | /
  *       ( )        ( )          \|/        |/                    |/
  *  ( )   |           \  ( )     (c)       ( )----( )            ( )
  *    \   |  ( )       \  |        \  ( )  /                 ( )  |
  *     \  |  /          \ |         \  |  /                    \  | ( )
  *      \ | /            \|          \ | /                      \ | /
  *       \|/             ( )          \|/         ( )            \|/
  *       ( )               \    (c)---(c)   ( )    | ( )         ( )
  *                          \   /       \   /      | /
  *                           \ /         \ /       |/
  *                           (c)         (c)------( )----( )
  *                             \         /
  *                              \       /
  *                              (c)---(c)</pre>
  *
  * If the anchor (s) is moved into the cycle at the base of the tree, then {@linkplain
  * #CO_BASE base co-candidate} relations (b) also appear.  The base co-candidates include
  * both <a href='../../../../../d/theory.xht#base-candidate' target='_top'>root
  * candidates</a> (left and right) and <a href='../../../../../d/theory.xht#cycle'
  * target='_top'>cyclers</a> (center).<pre>
  *
  *                     \    \  |     | /
  *                      \    \ |     |/
  *      ( )              \    \|    (v)-----(v)
  *       |       (v)-----(v)  (v)   /
  *   ( ) |                 \   |   /    (v)
  *     \ |                  \  |  /      | (v)               ( )( )
  *      \|                   \ | /       | /                  | /
  *      ( )      ( )          \|/        |/                   |/
  * ( )   |         \  ( )     (v)       (v)----(v)           ( )
  *   \   |  ( )     \  |        \  (v)  /                ( )  |
  *    \  |  /        \ |         \  |  /                   \  | ( )
  *     \ | /          \|          \ | /                     \ | /
  *      \|/           ( )          \|/         ( )           \|/
  *      (b)             \    (b)---(s)   (o)    | ( )        (b)
  *                       \   /       \   /      | /
  *                        \ /         \ /       |/
  *                        (b)         (b)------(o)----( )
  *                          \         /
  *                           \       /
  *                           (b)---(b)
  *
  *
  *                                   &lt;---</pre&gt;
  *
  * These cast relations are exclusive in the sense that <em>at most</em> one relation
  * applies for a person at any given moment.  The person is never both a voter and a
  * candidate to the anchor even in a tight cycle, but is rather a base co-candidate.  A
  * tight cycle is illustrated below, where the cast edges go left and right between the
  * person (b) and the anchor (s).<pre>
  *
  *      (v) (v)       (o)
  *   (v) |  /     (o) /
  *     \ | /       | /
  *      \|/  -->   |/
  *      (s)=======(b)---(o)
  *           &lt;--</pre&gt;
  *
  * Exclusivity is useful in visual styling, as for example in <a
  * href='../diff/DiffKey.html#ord'>difference ordering</a> and {@linkplain
  * votorola.s.gwt.mediawiki.ShadowLight shadow lighting}.
  */
public enum XCastRelation
{


    /** The person and the anchor are the same.  The symbol for this relation is 's'.
      */
    SELF( 's' ),


    /** The anchor is a recipient of the person's vote and the person is not a base
      * candidate.  The person is a voter to the anchor.  The symbol for this relation is
      * 'v'.
      *
      *     @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base
      *       candidate</a>
      */        // per INLDOC
    VOTER( 'v' ),


    /** Another candidate is the <em>direct</em> recipient of both the person's vote and
      * the anchor's vote.  The person is a co-voter to the anchor (and vice versa).  The
      * symbol for this relation is 'o'.
      */
    CO_VOTER( 'o' ),


    /** Both the person and the anchor are base candidates.  The person is a base
      * co-candidate to the anchor (and vice versa).  The symbol for this relation is 'b'.
      *
      *     @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base
      *       candidate</a>
      */        // per INLDOC
    CO_BASE( 'b' ),


    /** The person is a recipient of the anchor's vote and the anchor is not a base
      * candidate.  The person is a candidate to the anchor.  The symbol for this relation
      * is 'c'.
      *
      *     @see <a href='../../../../../d/theory.xht#base-candidate' target='_top'>base
      *       candidate</a>
      */        // per INLDOC
    CANDIDATE( 'c' ),


    /** The style symbol 'u' for the unknown cast relation.
      */
    UNKNOWN( 'u' );



    private XCastRelation( char _symbol ) { symbol = _symbol; }



   // --------------------------------------------------------------------------------


    /** Returns the character symbol of the relation.
      */
    public char symbol() { return symbol; }


        private final char symbol;


}