org.jgrapht.io.CSVFormat Maven / Gradle / Ivy

/*
 * (C) Copyright 2016-2017, by Dimitrios Michail and Contributors.
 *
 * JGraphT : a free Java graph-theory library
 *
 * This program and the accompanying materials are dual-licensed under
 * either
 *
 * (a) the terms of the GNU Lesser General Public License version 2.1
 * as published by the Free Software Foundation, or (at your option) any
 * later version.
 *
 * or (per the licensee's choosing)
 *
 * (b) the terms of the Eclipse Public License v1.0 as published by
 * the Eclipse Foundation.
 */
package org.jgrapht.io;

/**
 * Supported CSV formats.
 * 
 * 
 * 
 * 
 * Format {@link #EDGE_LIST} contains one edge per line. The following example
 * 
 * 
 * a,b
 * b,c
 * 
 * 
 * represents a graph with two edges: a->b and b->c.
 * 
 * 
 * 
 * Format {@link #ADJACENCY_LIST} contains the adjacency list of each vertex per line. The first
 * field on a line is a vertex while the remaining fields are its neighbors.
 * 
 * 
 * a,b
 * b,c,d
 * c,a,c,d
 * 
 * 
 * represents a graph with edges: a->b, b->c, b->d, c->a, c->c, c->d.
 * 
 * 
 * Mixed variants of {@link #EDGE_LIST} and {@link #ADJACENCY_LIST} are also considered valid. As an
 * example consider the following input
 * 
 * 
 * a,b
 * b,a
 * d,a
 * c,a,b
 * b,d,a
 * 
 * 
 * which represents a graph with edges: a->b, b->a, d->a, c->a, c->b, b->d,
 * b->a. Multiple occurrences of the same edge result into a multi-graph.
 * 
 * 
 * 
 * 
 * Format {@link #MATRIX} outputs an adjacency matrix representation of the graph. Each line
 * represents a vertex.
 * 
 * The following
 * 
 * 
 * 0,1,0,1,0
 * 1,0,0,0,0
 * 0,0,1,0,0
 * 0,1,0,1,0
 * 0,0,0,0,0
 * 
 * 
 * represents a graph with five vertices 1,2,3,4,5 which contains edges: 1->2, 1->4, 2->1,
 * 3->3, 4->2, 4->4.
 * 
 * 
 * In case {@link CSVFormat.Parameter#MATRIX_FORMAT_ZERO_WHEN_NO_EDGE} is not set the equivalent
 * format would be:
 * 
 * 
 * ,1,,1,
 * 1,,,,
 * ,,1,,
 * ,1,,1,
 * ,,,,
 * 
 * 
 * 
 * Weighted variants are also valid if {@link CSVFormat.Parameter#MATRIX_FORMAT_EDGE_WEIGHTS} is
 * set. The above example would then be:
 * 
 * 
 * ,1.0,,1.0,
 * 1.0,,,,
 * ,,1.0,,
 * ,1.0,,1.0,
 * ,,,,
 * 
 * 
 * If additionally {@link CSVFormat.Parameter#MATRIX_FORMAT_ZERO_WHEN_NO_EDGE} is set then a zero as
 * an integer means that the corresponding edge is missing, while a zero as a double means than the
 * edge exists and has zero weight.
 * 
 * 
 * If parameter {@link CSVFormat.Parameter#MATRIX_FORMAT_NODEID} is set then node identifiers are
 * also included as in the following example:
 * 
 * 
 * ,a,b,c,d,e
 * a,,1,,1,
 * b,1,,,,
 * c,,,1,,
 * d,,1,,1,
 * e,,,,,
 * 
 * 
 * In the above example the first line contains the node identifiers and the first field of each
 * line contain the vertex it corresponds to. In case node identifiers are present line-shuffled
 * input is also valid such as:
 * 
 *  * ,a,b,c,d,e
 * c,,,1,,
 * b,1,,,,
 * e,,,,,
 * d,,1,,1,
 * a,,1,,1,
 * 
 * 
 * The last example represents the graph with edges: a->b, a->d, b->a, c->c, d->b,
 * d->d.
 * 
 * 
 * 
 * 
 * @author Dimitrios Michail
 * @since August 2016
 *
 */
public enum CSVFormat
{
    /**
     * Edge list
     */
    EDGE_LIST,
    /**
     * Adjacency list
     */
    ADJACENCY_LIST,
    /**
     * Matrix
     */
    MATRIX;

    /**
     * Parameters that affect the behavior of CVS importers/exporters.
     */
    public enum Parameter
    {
        /**
         * Whether to import/export node ids. Only valid for the {@link CSVFormat#MATRIX MATRIX}
         * format.
         */
        MATRIX_FORMAT_NODEID,
        /**
         * Whether to import/export edge weights. Only valid for the {@link CSVFormat#MATRIX MATRIX}
         * format.
         */
        MATRIX_FORMAT_EDGE_WEIGHTS,
        /**
         * Whether the input/output contains zero for missing edges. Only valid for the
         * {@link CSVFormat#MATRIX MATRIX} format.
         */
        MATRIX_FORMAT_ZERO_WHEN_NO_EDGE,
    }

}

// End CSVFormat.java