From 5e291466fbbc45aed74f67a1b2e555d1f0c44d8f Mon Sep 17 00:00:00 2001 From: Sebastiano Tronto Date: Thu, 10 Oct 2024 19:49:48 +0200 Subject: Improved error messages and add some comments in nissy.h --- src/nissy.h | 120 +++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 91 insertions(+), 29 deletions(-) (limited to 'src/nissy.h') diff --git a/src/nissy.h b/src/nissy.h index 1fc1776..c78fb50 100644 --- a/src/nissy.h +++ b/src/nissy.h @@ -1,10 +1,17 @@ /* -If you include this file, you should also include the following: +This is libnissy (temporarily also known as h48), a Rubik's cube library. -inttypes, stdarg, stdbool, string +If you include this file, you should also use the following includes: -All the functions below return 0 in case of success and a positive -number in case of error, unless otherwise specified. +#include +#include +#include +#include + +All the functions below return 0 in case of success and a positive number +in case of error, unless otherwise specified. Errors are checked in code +order: for example if error code 1 is returned then it could that also +an error with code 2 or higher occurred. Arguments of type char [static 22] denote a cube in B32 format. Other available formats are H48 and SRC. See README.md for more info on @@ -18,40 +25,85 @@ A transformation must be given in the format for example 'rotation UF' or 'mirrored BL'. */ -/* Apply the secod argument as a permutation on the first argument */ +/* +Apply the secod argument as a permutation on the first argument. + +Return values: + 0 Valid result + 1 The given cube is invalid + 2 The given permutation is invalid + 9 The resulting cube is not solvable +*/ int64_t nissy_compose( const char cube[static 22], const char permutation[static 22], char result[static 22] ); -/* Compute the inverse of the given cube */ +/* +Compute the inverse of the given cube. + +Return values: + 0 Valid result + 1 The given cube is invalid + 9 The resulting cube is not solvable +*/ int64_t nissy_inverse( const char cube[static 22], char result[static 22] ); -/* Apply the given sequence of moves on the given cube */ +/* +Apply the given sequence of moves on the given cube. + +Return values: + 0 Valid result + 1 The given cube is invalid + 8 The given moves are invalid + 9 The resulting cube is not solvable +*/ int64_t nissy_applymoves( const char cube[static 22], const char *moves, char result[static 22] ); -/* Apply the single given transformation to the given cube */ +/* +Apply the single given transformation to the given cube. + +Return values: + 0 Valid result + 1 The given cube is invalid + 8 The given transformation is invalid + 9 The resulting cube is not solvable +*/ int64_t nissy_applytrans( const char cube[static 22], const char *transformation, char result[static 22] ); -/* Return the cube obtained by applying the given moves to the solved cube */ +/* +Apply the given moves to the solved cube. + +Return values: + 0 Valid result + 1 The given moves are invalid +*/ int64_t nissy_frommoves( const char *moves, char result[static 22] ); -/* Convert the given cube between the two given formats */ +/* +Convert the given cube between the two given formats. + +Return values: + 0 Valid result + 1 The given cube or format_in is invalid + 2 The resulting cube or format_out is invalid + 3 The resulting cube is inconsistent +*/ int64_t nissy_convert( const char *format_in, const char *format_out, @@ -70,40 +122,48 @@ int64_t nissy_getcube( ); /* -Returns the size of the data generated by nissy_gendata, when called with -the same parameters, or -1 in case of error. The returned value can be -slightly larger than the actual table size. +Compute the size of the data generated by nissy_gendata, when called with +the same parameters, or -1 in case of error. + +Return values: + -1 Error + >=0 The size of the table, in bytes */ int64_t nissy_datasize( const char *solver ); -/* Returns the number of bytes written, or -1 in case of error */ +/* +Compute the data for the given solver and store it in generated_data. + +Return values: + -1 Error + >=0 The size of the table, in bytes +*/ int64_t nissy_gendata( const char *solver, void *generated_data ); -/* Temporarily added to test h48 intermediate tables */ -int64_t nissy_derivedata( - const char *options, - const void *fulltable, - void *generated_data -); - -/* Returns 0 on positive check, 1 on error */ -int64_t nissy_checkdata( - const char *solver, - const void *data -); +/* +Print information on a data table via the provided callback writer. -/* Print information on a data table via the provided callback writer */ +Return values: + 0 No error + 1 The given data could not be read correctly +*/ int64_t nissy_datainfo( const void *table, void (*write)(const char *, ...) ); -/* Returns the number of solutions found, or -1 in case of error */ +/* +Solve the given cube using the given solver and options + +Return values: + -1 Error + >=0 The number of solutions found +*/ int64_t nissy_solve( const char cube[static 22], const char *solver, @@ -116,5 +176,7 @@ int64_t nissy_solve( char *solutions ); -/* Set a global logger function used by this library. */ +/* +Set a global logger function used by this library. +*/ void nissy_setlogger(void (*logger_function)(const char *, ...)); -- cgit v1.3