#define SN_NETWORK_INPUT_NUM(n) (n)->inputs_num
/**
- * Creates an empty comparator network and returns a pointer to it.
+ * Creates an empty comparator network and returns a pointer to it. The
+ * comparator network must be freed using sn_network_destroy().
*
* \param inputs_num Number of inputs the comparator network has.
- * \return Pointer to the comparator network or NULL on error.
+ * \return Pointer to the comparator network or \c NULL on error.
*/
sn_network_t *sn_network_create (int inputs_num);
* Clones an existing comparator network.
*
* \param n Comparator network to clone.
- * \return Copied sort network or NULL on error. The returned network must be
- * freed using sn_network_destroy().
+ * \return Copied sort network or \c NULL on error. The returned network must
+ * be freed using sn_network_destroy().
*/
sn_network_t *sn_network_clone (const sn_network_t *n);
/**
* Destroys a comparator network allocated with sn_network_create() or one of
- * the other methods returning a sn_network_t. This frees all allocated space.
+ * the other methods returning a \c sn_network_t. This frees all allocated
+ * space.
*
- * \param n The comparator network to destroy. May be NULL.
+ * \param n The comparator network to destroy. May be \c NULL.
*/
void sn_network_destroy (sn_network_t *n);
* Creates a new sort network using Batcher's Odd-Even-Mergesort algorithm.
*
* \param inputs_num Number of inputs / outputs of the sorting network.
- * \return A pointer to the newly allocated sorting network or NULL if an
+ * \return A pointer to the newly allocated sorting network or \c NULL if an
* invalid number of inputs was given or allocation failed.
*/
sn_network_t *sn_network_create_odd_even_mergesort (int inputs_num);
/**
+ * Creates a new sorting network using the Pairwise sorting algorithm published
+ * by Ian Parberry.
+ * \param inputs_num Number of inputs / outputs of the sorting network.
+ * \return A pointer to the newly allocated sorting network or \c NULL if an
+ * invalid number of inputs was given or allocation failed.
+ */
+sn_network_t *sn_network_create_pairwise (int inputs_num);
+
+/**
* Append a new stage to a comparator network.
*
* \param n The comparator network to which to add the stage.
*
* \param n Comparator network to work with.
* \return The number of comparators contained in the network or less than zero
- * on error (n is NULL).
+ * on error (\c n is \c NULL).
*/
int sn_network_get_comparator_num (const sn_network_t *n);
* comparator network. Otherwise, segmentation faults or memory corruption
* will occur.
* \return Zero on success, non-zero on failure.
+ * \see sn_stage_sort
*/
int sn_network_sort (sn_network_t *n, int *values);
*/
int sn_network_brute_force_check (sn_network_t *n);
+/**
+ * Prints the comparator network to \c STDOUT using a human readable
+ * representation.
+ *
+ * \param n The comparator network to display.
+ * \return Zero on success, non-zero on failure.
+ */
int sn_network_show (sn_network_t *n);
/**
*
* \param n0 First network.
* \param n1 Second network.
- * \return Newly allocated network with twice the number of inputs or NULL on
- * error.
+ * \return Newly allocated network with twice the number of inputs or \c NULL
+ * on error.
*/
sn_network_t *sn_network_combine_bitonic_merge (sn_network_t *n0, sn_network_t *n1);
*
* \param n0 First network.
* \param n1 Second network.
- * \return Newly allocated network or NULL on error.
+ * \return Newly allocated network or \c NULL on error.
*/
sn_network_t *sn_network_combine_odd_even_merge (sn_network_t *n0, sn_network_t *n1);
* Reads a comparator network from a open file handle.
*
* \param fh The FILE pointer to read from.
- * \return A newly allocated comparator network or NULL on error.
+ * \return A newly allocated comparator network or \c NULL on error.
* \see sn_network_read_file
*/
sn_network_t *sn_network_read (FILE *fh);
* Reads a comparator network from a file.
*
* \param file File name to read the network from.
- * \return A newly allocated comparator network or NULL on error.
+ * \return A newly allocated comparator network or \c NULL on error.
* \see sn_network_read
*/
sn_network_t *sn_network_read_file (const char *file);
* \param buffer Pointer to a buffer containing the comparator network in
* serialized form.
* \param buffer_size Size of the buffer (in bytes).
- * \return Pointer to the newly allocated comparator network or NULL on error.
+ * \return Pointer to the newly allocated comparator network or \c NULL on
+ * error.
* \see sn_network_serialize
*/
sn_network_t *sn_network_unserialize (char *buffer, size_t buffer_size);