From 79c9c600f7a620e3e804ff7783511ad7da7d8f93 Mon Sep 17 00:00:00 2001 From: Sebastiano Tronto Date: Fri, 11 Oct 2024 12:04:02 +0200 Subject: Error codes, documentation, change nisstype from string to flags --- src/nissy.h | 229 +++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 189 insertions(+), 40 deletions(-) (limited to 'src/nissy.h') diff --git a/src/nissy.h b/src/nissy.h index c78fb50..c019998 100644 --- a/src/nissy.h +++ b/src/nissy.h @@ -8,10 +8,9 @@ If you include this file, you should also use the following includes: #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. +All the functions return 0 or a positive integer in case of success and +a negative integer in case of error, unless otherwise specified. +You can see the list of error codes below, or use nissy_explainerror(). 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 @@ -25,14 +24,48 @@ A transformation must be given in the format for example 'rotation UF' or 'mirrored BL'. */ +/* Error codes */ +#define NISSY_OK INT64_C(0) +#define NISSY_WARNING_UNSOLVABLE INT64_C(-1) +#define NISSY_WARNING_NULL_CALLBACK INT64_C(-2) +#define NISSY_ERROR_INVALID_CUBE INT64_C(-10) +#define NISSY_ERROR_UNSOLVABLE_CUBE INT64_C(-11) +#define NISSY_ERROR_INVALID_MOVES INT64_C(-20) +#define NISSY_ERROR_INVALID_TRANS INT64_C(-30) +#define NISSY_ERROR_INVALID_FORMAT INT64_C(-40) +#define NISSY_ERROR_INVALID_SOLVER INT64_C(-50) +#define NISSY_ERROR_NULL_POINTER INT64_C(-60) +#define NISSY_ERROR_DATA INT64_C(-70) +#define NISSY_ERROR_OPTIONS INT64_C(-80) +#define NISSY_ERROR_INVALID_CODE INT64_C(-90) +#define NISSY_ERROR_UNKNOWN INT64_C(-999) + +/* Flags for NISS options */ +#define NISSY_NISSFLAG_NORMAL UINT8_C(1) +#define NISSY_NISSFLAG_INVERSE UINT8_C(2) +#define NISSY_NISSFLAG_MIXED UINT8_C(4) +#define NISSY_NISSFLAG_LINEAR \ + (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE) +#define NISSY_NISSFLAG_ALL \ + (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE | NISSY_NISSFLAG_MIXED) + /* Apply the secod argument as a permutation on the first argument. +Parameters: + cube - The first cube, in B32 format. + permutation - The second cube, in B32 format. This cube is treated as a + permutation and "applied" to the first cube. + result - The return parameter for the resulting cube, in B32 format. + Return values: - 0 Valid result - 1 The given cube is invalid - 2 The given permutation is invalid - 9 The resulting cube is not solvable + NISSY_OK - The cubes were composed succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is + either because at least on of the given cubes + was not solvable, or due to an unknown internal + error. + NISSY_ERROR_INVALID_CUBE - At least one of the given cubes is invalid. + NISSY_ERROR_UNKNOWN - An unknown error occurred. */ int64_t nissy_compose( const char cube[static 22], @@ -43,10 +76,17 @@ int64_t nissy_compose( /* Compute the inverse of the given cube. +Parameters: + cube - The cube to be inverted, in B32 format. + result - The return parameter for the resulting cube, in B32 format. + Return values: - 0 Valid result - 1 The given cube is invalid - 9 The resulting cube is not solvable + NISSY_OK - The cube was inverted succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is + either because the given cube was not solvable, + or due to an unknown internal error. + NISSY_ERROR_INVALID_CUBE - The given cube is invalid. + NISSY_ERROR_UNKNOWN - An unknown error occurred. */ int64_t nissy_inverse( const char cube[static 22], @@ -56,11 +96,18 @@ int64_t nissy_inverse( /* Apply the given sequence of moves on the given cube. +Parameters: + cube - The cube to move, in B32 format. + moves - The moves to apply to the cube. + result - The return parameter for the resulting cube, in B32 format. + Return values: - 0 Valid result - 1 The given cube is invalid - 8 The given moves are invalid - 9 The resulting cube is not solvable + NISSY_OK - The moves were applied succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is + either because the given cube was not solvable, + or due to an unknown internal error. + NISSY_ERROR_INVALID_CUBE - The given cube is invalid. + NISSY_ERROR_INVALID_MOVES - The given moves are invalid. */ int64_t nissy_applymoves( const char cube[static 22], @@ -71,11 +118,17 @@ int64_t nissy_applymoves( /* Apply the single given transformation to the given cube. +Parameters: + cube - The cube to be transformed, in B32 format. + transformation - The transformation in (rotation|mirrored) xy format. + result - The return parameter for the resulting cube, in B32 format. + Return values: - 0 Valid result - 1 The given cube is invalid - 8 The given transformation is invalid - 9 The resulting cube is not solvable + NISSY_OK - The transformation was performed succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is + probably due to an unknown internal error. + NISSY_ERROR_INVALID_CUBE - The given cube is invalid. + NISSY_ERROR_INVALID_TRANS - The given transformation is invalid. */ int64_t nissy_applytrans( const char cube[static 22], @@ -86,9 +139,15 @@ int64_t nissy_applytrans( /* Apply the given moves to the solved cube. +Parameters: + moves - The moves to be applied to the solved cube. + result - Return parameter for the resulting cube, in B32 format. + Return values: - 0 Valid result - 1 The given moves are invalid + NISSY_OK - The moves were performed succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is + probably due to an unknown internal error. + NISSY_ERROR_INVALID_MOVES - The given moves are invalid. */ int64_t nissy_frommoves( const char *moves, @@ -98,20 +157,45 @@ int64_t nissy_frommoves( /* Convert the given cube between the two given formats. +Parameters: + format_in - The input format. + format_out - The output format. + string - The cube, in format_in format. + result - Return parameter for the cube in format_out format. Must be + large enough to contains the cube in this format. + 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 + NISSY_OK - The conversion was performed succesfully. + NISSY_ERROR_INVALID_CUBE - The given cube is invalid. + NISSY_ERROR_INVALID_FORMAT - At least one of the given formats is invalid. + NISSY_ERROR_UNKNOWN - An unknown error occurred. */ int64_t nissy_convert( const char *format_in, const char *format_out, - const char *cube_string, + const char *cube, char *result ); -/* Get the cube with the given ep, eo, cp and co values. */ +/* +Get the cube with the given ep, eo, cp and co values. The values must be in the +ranges specified below, but if the option "fix" is given any values outside its +range will be adjusted before using it. The option "fix" also fixes parity and +orientation issues, resulting always in a solvable cube. + +Parameters: + ep - The edge permutation, 0 <= ep <= 479001600 (12!) + eo - The edge orientation, 0 <= eo <= 2047 (2^11) + cp - The corner permutation, 0 <= cp <= 40320 (8!) + co - The corner orientation, 0 <= co <= 2187 (3^7) + options - Other options. + result - The return parameter for the resulting cube, in B32 format. + +Return values: + NISSY_OK - The cube was generated succesfully. + NISSY_WARNING_UNSOLVABLE - The resulting cube is unsolvable. + NISSY_ERROR_OPTIONS - One or more of the given parameters is invalid. +*/ int64_t nissy_getcube( int64_t ep, int64_t eo, @@ -125,9 +209,13 @@ int64_t nissy_getcube( Compute the size of the data generated by nissy_gendata, when called with the same parameters, or -1 in case of error. +Parameters: + solver - The name of the solver. + Return values: - -1 Error - >=0 The size of the table, in bytes + NISSY_ERROR_INVALID_SOLVER - The given solver is not known. + NISSY_ERROR_UNKNOWN - An unknown error occurred. + Any value >= 0 - The size of the data, in bytes. */ int64_t nissy_datasize( const char *solver @@ -136,38 +224,71 @@ int64_t nissy_datasize( /* Compute the data for the given solver and store it in generated_data. +Parameters: + solver - The name of the solver. + data - The return parameter for the generated data. Must be large enoguh + to contain the whole data. It is advised to use nissy_datasize to + check how much memory is needed. + Return values: - -1 Error - >=0 The size of the table, in bytes + NISSY_ERROR_INVALID_SOLVER - The given solver is not known. + NISSY_ERROR_UNKNOWN - An error occurred while generating the data. + Any value >= 0 - The size of the data, in bytes. */ int64_t nissy_gendata( const char *solver, - void *generated_data + void *data ); /* Print information on a data table via the provided callback writer. +Parameters: + data - The data + write - A callback writer with the same signature as printf(3). + Return values: - 0 No error - 1 The given data could not be read correctly + NISSY_OK - The data is correct. + NISSY_ERROR_DATA - The data contains errors. */ int64_t nissy_datainfo( - const void *table, + const void *data, void (*write)(const char *, ...) ); /* -Solve the given cube using the given solver and options +Solve the given cube using the given solver and options. + +Parameters: + cube - The cube to solver, in B32 format. + solver - The name of the solver. + nissflag - The flags for NISS (linear, inverse, mixed, or combinations). + minmoves - The minimum number of moves for a solution. + maxmoves - The maximum number of moves for a solution. + maxsolutions - The maximum number of solutions. + optimal - If set to a non-negative value, the maximum number of moves + above the optimal solution length. + data - The data for the solver. Can be computed with gendata. + solutions - The return parameter for the solutions. Must be large enough + to store all found solutions. The solutions are separated by + a '\n' (newline) and a '\0' (NULL character) terminates the + list. + TODO: replace with callback writer. Return values: - -1 Error - >=0 The number of solutions found + NISSY_OK - Cube solved succesfully. + NISSY_ERROR_INVALID_CUBE - The given cube is invalid. + NISSY_ERROR_UNSOLVABLE_CUBE - The given cube is valid, but not solvable with + the given solver. + NISSY_ERROR_OPTIONS - One or more of the given options are invalid. + NISSY_ERROR_NULL_POINTER - One of the provided pointers is null. + NISSY_ERROR_INVALID_SOLVER - The given solver is not known. + Any value >= 0 - The number of solutions found. */ int64_t nissy_solve( const char cube[static 22], const char *solver, - const char *nisstype, /* TODO: remove, use flags */ + uint8_t nissflag, int8_t minmoves, int8_t maxmoves, int64_t maxsolutions, @@ -178,5 +299,33 @@ int64_t nissy_solve( /* Set a global logger function used by this library. + +Parameters: + write - A callback writer with the same signature as printf(3). + +Return values: + NISSY_OK - Logger set succesfully. + NISSY_WARNING_NULL_CALLBACK - The provided callback writer is NULL. */ -void nissy_setlogger(void (*logger_function)(const char *, ...)); +int64_t nissy_setlogger( + void (*logger_function)(const char *, ...) +); + +/* +Print an explanation of the given error code via the provided callback writer. + +Parameters: + error_code - The error code to be explained. It can be any value returned + by a function in this library, not necessarily an error. + write - A callback writer with the same signature as printf(3). + Must be non-NULL. + +Return values: + NISSY_OK - The error code is known. + NISSY_WARNING_NULL_CALLBACK - The provided callback writer is NULL. + NISSY_ERROR_INVALID_CODE - The error code is unknown. +*/ +int64_t nissy_explainerror( + int64_t error_code, + void (*write)(const char *, ...) +); -- cgit v1.3