diff options
Diffstat (limited to 'src/nissy.h')
| -rw-r--r-- | src/nissy.h | 130 |
1 files changed, 56 insertions, 74 deletions
diff --git a/src/nissy.h b/src/nissy.h index 6d78778..8f4f363 100644 --- a/src/nissy.h +++ b/src/nissy.h | |||
| @@ -1,13 +1,6 @@ | |||
| 1 | /* | 1 | /* |
| 2 | This is libnissy (temporarily also known as h48), a Rubik's cube library. | 2 | This is libnissy (temporarily also known as h48), a Rubik's cube library. |
| 3 | 3 | ||
| 4 | If you include this file, you should also use the following includes: | ||
| 5 | |||
| 6 | #include <inttypes.h> | ||
| 7 | #include <stdarg.h> | ||
| 8 | #include <stdbool.h> | ||
| 9 | #include <string.h> | ||
| 10 | |||
| 11 | All the functions return 0 or a positive integer in case of success and | 4 | All the functions return 0 or a positive integer in case of success and |
| 12 | a negative integer in case of error, unless otherwise specified. See at | 5 | a negative integer in case of error, unless otherwise specified. See at |
| 13 | the bottom of this file for the list of error codes and their meaning. | 6 | the bottom of this file for the list of error codes and their meaning. |
| @@ -24,20 +17,29 @@ A transformation must be given in the format | |||
| 24 | for example 'rotation UF' or 'mirrored BL'. | 17 | for example 'rotation UF' or 'mirrored BL'. |
| 25 | */ | 18 | */ |
| 26 | 19 | ||
| 20 | |||
| 21 | /* Constants *****************************************************************/ | ||
| 22 | |||
| 27 | /* Some constants for size for I/O buffers */ | 23 | /* Some constants for size for I/O buffers */ |
| 28 | #define NISSY_SIZE_B32 UINT64_C(22) | 24 | #define NISSY_SIZE_B32 22U |
| 29 | #define NISSY_SIZE_H48 UINT64_C(88) | 25 | #define NISSY_SIZE_H48 88U |
| 30 | #define NISSY_SIZE_TRANSFORMATION UINT64_C(12) | 26 | #define NISSY_SIZE_TRANSFORMATION 12U |
| 31 | 27 | ||
| 32 | /* Flags for NISS options */ | 28 | /* Flags for NISS options */ |
| 33 | #define NISSY_NISSFLAG_NORMAL UINT8_C(1) | 29 | #define NISSY_NISSFLAG_NORMAL 1U |
| 34 | #define NISSY_NISSFLAG_INVERSE UINT8_C(2) | 30 | #define NISSY_NISSFLAG_INVERSE 2U |
| 35 | #define NISSY_NISSFLAG_MIXED UINT8_C(4) | 31 | #define NISSY_NISSFLAG_MIXED 4U |
| 36 | #define NISSY_NISSFLAG_LINEAR \ | 32 | #define NISSY_NISSFLAG_LINEAR \ |
| 37 | (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE) | 33 | (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE) |
| 38 | #define NISSY_NISSFLAG_ALL \ | 34 | #define NISSY_NISSFLAG_ALL \ |
| 39 | (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE | NISSY_NISSFLAG_MIXED) | 35 | (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE | NISSY_NISSFLAG_MIXED) |
| 40 | 36 | ||
| 37 | /* The solved cube in B32 format */ | ||
| 38 | #define NISSY_SOLVED_CUBE "ABCDEFGH=ABCDEFGHIJKL" | ||
| 39 | |||
| 40 | |||
| 41 | /* Library functions *********************************************************/ | ||
| 42 | |||
| 41 | /* | 43 | /* |
| 42 | Apply the secod argument as a permutation on the first argument. | 44 | Apply the secod argument as a permutation on the first argument. |
| 43 | 45 | ||
| @@ -56,7 +58,7 @@ Return values: | |||
| 56 | NISSY_ERROR_INVALID_CUBE - At least one of the given cubes is invalid. | 58 | NISSY_ERROR_INVALID_CUBE - At least one of the given cubes is invalid. |
| 57 | NISSY_ERROR_UNKNOWN - An unknown error occurred. | 59 | NISSY_ERROR_UNKNOWN - An unknown error occurred. |
| 58 | */ | 60 | */ |
| 59 | int64_t nissy_compose( | 61 | long long nissy_compose( |
| 60 | const char cube[static NISSY_SIZE_B32], | 62 | const char cube[static NISSY_SIZE_B32], |
| 61 | const char permutation[static NISSY_SIZE_B32], | 63 | const char permutation[static NISSY_SIZE_B32], |
| 62 | char result[static NISSY_SIZE_B32] | 64 | char result[static NISSY_SIZE_B32] |
| @@ -77,7 +79,7 @@ Return values: | |||
| 77 | NISSY_ERROR_INVALID_CUBE - The given cube is invalid. | 79 | NISSY_ERROR_INVALID_CUBE - The given cube is invalid. |
| 78 | NISSY_ERROR_UNKNOWN - An unknown error occurred. | 80 | NISSY_ERROR_UNKNOWN - An unknown error occurred. |
| 79 | */ | 81 | */ |
| 80 | int64_t nissy_inverse( | 82 | long long nissy_inverse( |
| 81 | const char cube[static NISSY_SIZE_B32], | 83 | const char cube[static NISSY_SIZE_B32], |
| 82 | char result[static NISSY_SIZE_B32] | 84 | char result[static NISSY_SIZE_B32] |
| 83 | ); | 85 | ); |
| @@ -99,7 +101,7 @@ Return values: | |||
| 99 | NISSY_ERROR_INVALID_MOVES - The given moves are invalid. | 101 | NISSY_ERROR_INVALID_MOVES - The given moves are invalid. |
| 100 | NISSY_ERROR_NULL_POINTER - The 'moves' argument is NULL. | 102 | NISSY_ERROR_NULL_POINTER - The 'moves' argument is NULL. |
| 101 | */ | 103 | */ |
| 102 | int64_t nissy_applymoves( | 104 | long long nissy_applymoves( |
| 103 | const char cube[static NISSY_SIZE_B32], | 105 | const char cube[static NISSY_SIZE_B32], |
| 104 | const char *moves, | 106 | const char *moves, |
| 105 | char result[static NISSY_SIZE_B32] | 107 | char result[static NISSY_SIZE_B32] |
| @@ -120,33 +122,13 @@ Return values: | |||
| 120 | NISSY_ERROR_INVALID_CUBE - The given cube is invalid. | 122 | NISSY_ERROR_INVALID_CUBE - The given cube is invalid. |
| 121 | NISSY_ERROR_INVALID_TRANS - The given transformation is invalid. | 123 | NISSY_ERROR_INVALID_TRANS - The given transformation is invalid. |
| 122 | */ | 124 | */ |
| 123 | int64_t nissy_applytrans( | 125 | long long nissy_applytrans( |
| 124 | const char cube[static NISSY_SIZE_B32], | 126 | const char cube[static NISSY_SIZE_B32], |
| 125 | const char transformation[static NISSY_SIZE_TRANSFORMATION], | 127 | const char transformation[static NISSY_SIZE_TRANSFORMATION], |
| 126 | char result[static NISSY_SIZE_B32] | 128 | char result[static NISSY_SIZE_B32] |
| 127 | ); | 129 | ); |
| 128 | 130 | ||
| 129 | /* | 131 | /* |
| 130 | Apply the given moves to the solved cube. | ||
| 131 | |||
| 132 | Parameters: | ||
| 133 | moves - The moves to be applied to the solved cube. Must be a | ||
| 134 | NULL-terminated string. | ||
| 135 | result - Return parameter for the resulting cube, in B32 format. | ||
| 136 | |||
| 137 | Return values: | ||
| 138 | NISSY_OK - The moves were performed succesfully. | ||
| 139 | NISSY_WARNING_UNSOLVABLE - The resulting cube is not solvable. This is | ||
| 140 | probably due to an unknown internal error. | ||
| 141 | NISSY_ERROR_INVALID_MOVES - The given moves are invalid. | ||
| 142 | NISSY_ERROR_NULL_POINTER - The 'moves' argument is NULL. | ||
| 143 | */ | ||
| 144 | int64_t nissy_frommoves( | ||
| 145 | const char *moves, | ||
| 146 | char result[static NISSY_SIZE_B32] | ||
| 147 | ); | ||
| 148 | |||
| 149 | /* | ||
| 150 | Convert the given cube between the two given formats. | 132 | Convert the given cube between the two given formats. |
| 151 | 133 | ||
| 152 | Parameters: | 134 | Parameters: |
| @@ -165,11 +147,11 @@ Return values: | |||
| 165 | NISSY_ERROR_NULL_POINTER - At least one of 'format_in', 'format_out' or | 147 | NISSY_ERROR_NULL_POINTER - At least one of 'format_in', 'format_out' or |
| 166 | 'cube_string' arguments is NULL. | 148 | 'cube_string' arguments is NULL. |
| 167 | */ | 149 | */ |
| 168 | int64_t nissy_convert( | 150 | long long nissy_convert( |
| 169 | const char *format_in, | 151 | const char *format_in, |
| 170 | const char *format_out, | 152 | const char *format_out, |
| 171 | const char *cube_string, | 153 | const char *cube_string, |
| 172 | uint64_t result_size, | 154 | unsigned result_size, |
| 173 | char result[result_size] | 155 | char result[result_size] |
| 174 | ); | 156 | ); |
| 175 | 157 | ||
| @@ -192,11 +174,11 @@ Return values: | |||
| 192 | NISSY_WARNING_UNSOLVABLE - The resulting cube is unsolvable. | 174 | NISSY_WARNING_UNSOLVABLE - The resulting cube is unsolvable. |
| 193 | NISSY_ERROR_OPTIONS - One or more of the given parameters is invalid. | 175 | NISSY_ERROR_OPTIONS - One or more of the given parameters is invalid. |
| 194 | */ | 176 | */ |
| 195 | int64_t nissy_getcube( | 177 | long long nissy_getcube( |
| 196 | int64_t ep, | 178 | long long ep, |
| 197 | int64_t eo, | 179 | long long eo, |
| 198 | int64_t cp, | 180 | long long cp, |
| 199 | int64_t co, | 181 | long long co, |
| 200 | const char *options, | 182 | const char *options, |
| 201 | char result[static NISSY_SIZE_B32] | 183 | char result[static NISSY_SIZE_B32] |
| 202 | ); | 184 | ); |
| @@ -214,7 +196,7 @@ Return values: | |||
| 214 | NISSY_ERROR_UNKNOWN - An unknown error occurred. | 196 | NISSY_ERROR_UNKNOWN - An unknown error occurred. |
| 215 | Any value >= 0 - The size of the data, in bytes. | 197 | Any value >= 0 - The size of the data, in bytes. |
| 216 | */ | 198 | */ |
| 217 | int64_t nissy_datasize( | 199 | long long nissy_datasize( |
| 218 | const char *solver | 200 | const char *solver |
| 219 | ); | 201 | ); |
| 220 | 202 | ||
| @@ -233,9 +215,9 @@ Return values: | |||
| 233 | NISSY_ERROR_UNKNOWN - An error occurred while generating the data. | 215 | NISSY_ERROR_UNKNOWN - An error occurred while generating the data. |
| 234 | Any value >= 0 - The size of the data, in bytes. | 216 | Any value >= 0 - The size of the data, in bytes. |
| 235 | */ | 217 | */ |
| 236 | int64_t nissy_gendata( | 218 | long long nissy_gendata( |
| 237 | const char *solver, | 219 | const char *solver, |
| 238 | uint64_t data_size, | 220 | unsigned long long data_size, |
| 239 | char data[data_size] | 221 | char data[data_size] |
| 240 | ); | 222 | ); |
| 241 | 223 | ||
| @@ -250,8 +232,8 @@ Return values: | |||
| 250 | NISSY_OK - The data is valid. | 232 | NISSY_OK - The data is valid. |
| 251 | NISSY_ERROR_DATA - The data is invalid. | 233 | NISSY_ERROR_DATA - The data is invalid. |
| 252 | */ | 234 | */ |
| 253 | int64_t nissy_checkdata( | 235 | long long nissy_checkdata( |
| 254 | uint64_t data_size, | 236 | unsigned long long data_size, |
| 255 | const char data[data_size] | 237 | const char data[data_size] |
| 256 | ); | 238 | ); |
| 257 | 239 | ||
| @@ -284,17 +266,17 @@ Return values: | |||
| 284 | NISSY_ERROR_NULL_POINTER - The 'solver' argument is null. | 266 | NISSY_ERROR_NULL_POINTER - The 'solver' argument is null. |
| 285 | Any value >= 0 - The number of solutions found. | 267 | Any value >= 0 - The number of solutions found. |
| 286 | */ | 268 | */ |
| 287 | int64_t nissy_solve( | 269 | long long nissy_solve( |
| 288 | const char cube[static NISSY_SIZE_B32], | 270 | const char cube[static NISSY_SIZE_B32], |
| 289 | const char *solver, | 271 | const char *solver, |
| 290 | uint8_t nissflag, | 272 | unsigned nissflag, |
| 291 | int8_t minmoves, | 273 | unsigned minmoves, |
| 292 | int8_t maxmoves, | 274 | unsigned maxmoves, |
| 293 | int64_t maxsolutions, | 275 | unsigned maxsolutions, |
| 294 | int8_t optimal, | 276 | int optimal, |
| 295 | uint64_t data_size, | 277 | unsigned long long data_size, |
| 296 | const char data[data_size], | 278 | const char data[data_size], |
| 297 | uint64_t sols_size, | 279 | unsigned sols_size, |
| 298 | char sols[sols_size] | 280 | char sols[sols_size] |
| 299 | ); | 281 | ); |
| 300 | 282 | ||
| @@ -308,18 +290,18 @@ Return values: | |||
| 308 | NISSY_OK - Logger set succesfully. No warning or error is goind to be given | 290 | NISSY_OK - Logger set succesfully. No warning or error is goind to be given |
| 309 | if the logger is NULL or invalid. | 291 | if the logger is NULL or invalid. |
| 310 | */ | 292 | */ |
| 311 | int64_t nissy_setlogger( | 293 | long long nissy_setlogger( |
| 312 | void (*logger_function)(const char *, ...) | 294 | void (*logger_function)(const char *, ...) |
| 313 | ); | 295 | ); |
| 314 | 296 | ||
| 315 | 297 | ||
| 316 | /* Error codes */ | 298 | /* Error codes ***************************************************************/ |
| 317 | 299 | ||
| 318 | /* | 300 | /* |
| 319 | The value NISSY_OK denotes a success. If returned by solve, it means | 301 | The value NISSY_OK denotes a success. If returned by solve, it means |
| 320 | that no solution has been found. | 302 | that no solution has been found. |
| 321 | */ | 303 | */ |
| 322 | #define NISSY_OK INT64_C(0) | 304 | #define NISSY_OK 0LL |
| 323 | 305 | ||
| 324 | /* | 306 | /* |
| 325 | The value NISSY_WARNING_UNSOLVABLE is a warning. It means that the | 307 | The value NISSY_WARNING_UNSOLVABLE is a warning. It means that the |
| @@ -327,44 +309,44 @@ operation was completed succesfully, but the resulting cube is in an | |||
| 327 | unsolvable state. This could be intended, for example if the user has | 309 | unsolvable state. This could be intended, for example if the user has |
| 328 | provided an unsolvable cube as input. | 310 | provided an unsolvable cube as input. |
| 329 | */ | 311 | */ |
| 330 | #define NISSY_WARNING_UNSOLVABLE INT64_C(-1) | 312 | #define NISSY_WARNING_UNSOLVABLE -1LL |
| 331 | 313 | ||
| 332 | /* | 314 | /* |
| 333 | The value NISSY_ERROR_INVALID_CUBE means that the provided cube is | 315 | The value NISSY_ERROR_INVALID_CUBE means that the provided cube is |
| 334 | invalid. It could be written in an unknown format, or in a format | 316 | invalid. It could be written in an unknown format, or in a format |
| 335 | different from what specified, or simply ill-formed. | 317 | different from what specified, or simply ill-formed. |
| 336 | */ | 318 | */ |
| 337 | #define NISSY_ERROR_INVALID_CUBE INT64_C(-10) | 319 | #define NISSY_ERROR_INVALID_CUBE -10LL |
| 338 | 320 | ||
| 339 | /* | 321 | /* |
| 340 | The value NISSY_ERROR_UNSOLVABLE_CUBE means that the provided cube is | 322 | The value NISSY_ERROR_UNSOLVABLE_CUBE means that the provided cube is |
| 341 | in an unsolvable state. | 323 | in an unsolvable state. |
| 342 | */ | 324 | */ |
| 343 | #define NISSY_ERROR_UNSOLVABLE_CUBE INT64_C(-11) | 325 | #define NISSY_ERROR_UNSOLVABLE_CUBE -11LL |
| 344 | 326 | ||
| 345 | /* | 327 | /* |
| 346 | The value NISSY_ERROR_INVALID_MOVES means that the given moves are | 328 | The value NISSY_ERROR_INVALID_MOVES means that the given moves are |
| 347 | invalid. | 329 | invalid. |
| 348 | */ | 330 | */ |
| 349 | #define NISSY_ERROR_INVALID_MOVES INT64_C(-20) | 331 | #define NISSY_ERROR_INVALID_MOVES -20LL |
| 350 | 332 | ||
| 351 | /* | 333 | /* |
| 352 | The value NISSY_ERROR_INVALID_TRANS means that the given transformation | 334 | The value NISSY_ERROR_INVALID_TRANS means that the given transformation |
| 353 | is invalid. | 335 | is invalid. |
| 354 | */ | 336 | */ |
| 355 | #define NISSY_ERROR_INVALID_TRANS INT64_C(-30) | 337 | #define NISSY_ERROR_INVALID_TRANS -30LL |
| 356 | 338 | ||
| 357 | /* | 339 | /* |
| 358 | The value NISSY_ERROR_INVALID_FORMAT means that the given format is | 340 | The value NISSY_ERROR_INVALID_FORMAT means that the given format is |
| 359 | not known. | 341 | not known. |
| 360 | */ | 342 | */ |
| 361 | #define NISSY_ERROR_INVALID_FORMAT INT64_C(-40) | 343 | #define NISSY_ERROR_INVALID_FORMAT -40LL |
| 362 | 344 | ||
| 363 | /* | 345 | /* |
| 364 | The value NISSY_ERROR_INVALID_SOLVER means that the given solver is | 346 | The value NISSY_ERROR_INVALID_SOLVER means that the given solver is |
| 365 | not known. | 347 | not known. |
| 366 | */ | 348 | */ |
| 367 | #define NISSY_ERROR_INVALID_SOLVER INT64_C(-50) | 349 | #define NISSY_ERROR_INVALID_SOLVER -50LL |
| 368 | 350 | ||
| 369 | /* | 351 | /* |
| 370 | The value NISSY_ERROR_NULL_POINTER means that one of the provided pointer | 352 | The value NISSY_ERROR_NULL_POINTER means that one of the provided pointer |
| @@ -372,32 +354,32 @@ arguments is NULL. For example, it may be returned by solve when called | |||
| 372 | with a solver that requires some pre-computed data, but the provided | 354 | with a solver that requires some pre-computed data, but the provided |
| 373 | data is NULL. | 355 | data is NULL. |
| 374 | */ | 356 | */ |
| 375 | #define NISSY_ERROR_NULL_POINTER INT64_C(-60) | 357 | #define NISSY_ERROR_NULL_POINTER -60LL |
| 376 | 358 | ||
| 377 | /* | 359 | /* |
| 378 | The value NISSY_ERROR_BUFFER_SIZE means that one of the buffers provided | 360 | The value NISSY_ERROR_BUFFER_SIZE means that one of the buffers provided |
| 379 | is too small. For example, it could be too small to hold the result or | 361 | is too small. For example, it could be too small to hold the result or |
| 380 | too small to hold the data generated by gendata. | 362 | too small to hold the data generated by gendata. |
| 381 | */ | 363 | */ |
| 382 | #define NISSY_ERROR_BUFFER_SIZE INT64_C(-61) | 364 | #define NISSY_ERROR_BUFFER_SIZE -61LL |
| 383 | 365 | ||
| 384 | /* | 366 | /* |
| 385 | The value NISSY_ERROR_DATA means that the provided data is invalid. For | 367 | The value NISSY_ERROR_DATA means that the provided data is invalid. For |
| 386 | example, it may be returned by solve when called with incompatible solver | 368 | example, it may be returned by solve when called with incompatible solver |
| 387 | and data arguments. | 369 | and data arguments. |
| 388 | */ | 370 | */ |
| 389 | #define NISSY_ERROR_DATA INT64_C(-70) | 371 | #define NISSY_ERROR_DATA -70LL |
| 390 | 372 | ||
| 391 | /* | 373 | /* |
| 392 | The value NISSY_ERROR_OPTIONS means that one or more of the given options | 374 | The value NISSY_ERROR_OPTIONS means that one or more of the given options |
| 393 | are invalid. For example, it may be returned by solve when called with | 375 | are invalid. For example, it may be returned by solve when called with |
| 394 | a negative maximum number of solutions. | 376 | a negative maximum number of solutions. |
| 395 | */ | 377 | */ |
| 396 | #define NISSY_ERROR_OPTIONS INT64_C(-80) | 378 | #define NISSY_ERROR_OPTIONS -80LL |
| 397 | 379 | ||
| 398 | /* | 380 | /* |
| 399 | The value NISSY_ERROR_UNKNOWN denotes an unexpected error. It probably | 381 | The value NISSY_ERROR_UNKNOWN denotes an unexpected error. It probably |
| 400 | means that there some bug in this library. If you can, report any error | 382 | means that there some bug in this library. If you can, report any error |
| 401 | of this kind to sebastiano@tronto.net. Thanks! | 383 | of this kind to sebastiano@tronto.net. Thanks! |
| 402 | */ | 384 | */ |
| 403 | #define NISSY_ERROR_UNKNOWN INT64_C(-999) | 385 | #define NISSY_ERROR_UNKNOWN -999LL |
