Big changes to the interface

1 files changed, 52 insertions, 109 deletions

diff --git a/cube.h b/cube.h
index 889569f..d8896d8 100644
--- a/cube.h
+++ b/cube.h
@@ -17,6 +17,7 @@ corners is with respect to U/D.
 The permutation of the center pieces is not stored. This means that the
 cube is assumed to be in a fixed orientation.
 
+TODO: define EO and CO better, explain how to use them
 TODO: encode centers?
 
 The exact cube type structure depends on your system's configuration. If
@@ -24,22 +25,22 @@ you operate on the cube only via the functions provided below, you don't
 need to worry about this.
 ******************************************************************************/
 
-#ifdef CUBE_AVX2
-typedef __m256i cube_t;
-#else
 typedef struct {
-        uint8_t c[8];   /* Corners */
-        uint8_t e[12];  /* Edges   */
+        uint8_t corner[8];
+        uint8_t edge[12];
 } cube_t;
-#endif
 
 /* Returns a copy of the solved cube */
 cube_t solvedcube(void);
 
 /* Basic checks on the cube */
+bool isconsistent(cube_t);
 bool issolvable(cube_t);
-bool equal(cube_t, cube_t);
 bool issolved(cube_t);
+bool equal(cube_t, cube_t);
+
+/* All functions can return an error value, use iserror() to check this */
+bool iserror(cube_t);
 
 /* Apply the second cube on the first as a move sequence */
 cube_t compose(cube_t, cube_t);
@@ -47,134 +48,75 @@ cube_t compose(cube_t, cube_t);
 /* Invert the cube */
 cube_t inverse(cube_t);
 
-/* All functions can return an error value, use iserror() to check this */
-bool iserror(cube_t);
-
-/******************************************************************************
-Moves and transformations
-
-Moves and transformations are represented each as an (unsigned) 8 bit integer.
+/* Check if a cube represent a valid state (possibly unsolvable) */
 
-Moves are numbered as follows:
-U=0  U2=1  U'=2  D=3  D2=4  D'=5
-R=6  R2=7  R'=8  L=9  L2=10 L'=11
-F=12 F2=13 F'=14 B=15 B2=16 B'=17
+/* TODO comment on these and the format for moves and trans */
+/* For trans, only one trans is supported */
+cube_t applymoves(cube_t, char *);
+cube_t applytrans(cube_t, char *);
 
-TODO: NISS
+/******************************************************************************
+Read / write utilities
 
-TODO: Extend the moveset?
+Reading and writing is not done directly via stdin / stdout, but via an
+array of char (called buf in the prototypes below).
 
-Transformations can be either simple rotations or a rotation composed
-with a mirroring.  A composed rotation + mirror is obtained by applying
-the corresponding rotation to the solved cube mirrored along the M plane.
+Multiple representations of the cube as text are supported:
 
-For example, to apply the transformation RBm (mirrored RB) to a cube C:
-        1. Apply a mirror along the M plane to the solved cube
-        2. Rotate the mirrored cube with z' y2
-        3. Apply the cube C to the transformed solved cube
-        4. Apply the transformations of step 1a and 1b in reverse
+- H48: a human-readable format.
+  Each edge is represented by two letters denoting the sides it
+  belongs to and one number denoting its orientation (0 oriented, 1
+  mis-oriented). Similarly, each corner is represented by three letters and
+  a number (0 oriented, 1 twisted clockwise, 2 twisted counter-clockwise).
 
-See cube.c for a full list of transformations.
-******************************************************************************/
+  The solved cube looks like this:
 
-typedef uint8_t move_t;
-typedef uint8_t trans_t;
+  UF0 UB0 DB0 DF0 UR0 UL0 DL0 DR0 FR0 FL0 BL0 BR0
+  UFR0 UBL0 DFL0 DBR0 UFL0 UBR0 DFR0 DBL0
 
-/* Apply a move or a transformation on the cube */
-cube_t move(cube_t, move_t);
-cube_t transform(cube_t, trans_t);
+  The cube after the moves R'U'F looks like this:
 
-/******************************************************************************
-Read / write utilities
+  FL1 BR0 DB0 UR1 UF0 UB0 DL0 FR0 UL1 DF1 BL0 DR0
+  UBL1 DBR1 UFR2 DFR2 DFL2 UBL2 UFL2 DBL0
 
-Reading and writing is not done directly via stdin / stdout, but via an
-array of char (called buf in the prototypes below).
+  Whitespace (including newlines) between pieces is ignored when reading the
+  cube. A single whitespace character is added between pieces when writing.
 
-Multiple representations of the cube as text are supported, although
-not all of them are supported for both reading and writing. See below
-for details. More formats may be supported in the future.
+- SRC: format used to generate code for internal use.
+  In cube.c, a type called cube_array_t is defined and used for basic,
+  non-performance-critical methods. If OUT is the output in SRC format,
+  the following line can be used to declare a new cube object:
 
-Moves are read using the standard notation. Each move (U, D, R, L, F,
-B) can be followed by a modifier (1, 2, 3, '). Whitespace (spaces, tabs,
-newlines) are ignored. Parantheses and other notation is not supported.
-TODO: parantheses for NISS
+cube_array_t cube = OUT
+      
+- AVX: analogue to SRC, but for the AVX2 internal representation of the cube.
 
-For how transformations are read or written, see cube.c.
+Not all formats are supported for both reading and writing. More formats
+may be supported in the future.
 ******************************************************************************/
 
-/* The different formats for reading or writing the cube */
-typedef enum {
-        H48, /* H48 is a human-readable format.
-              *
-              * Each edge is represented by two letters denoting the sides it
-              * belongs to and one number denoting its orientation (0 oriented,
-              * 1 mis-oriented). Similarly, each corner is represented by three
-              * letters and a number (0 oriented, 1 twisted clockwise, 2
-              * twisted counter-clockwise).
-              *
-              * The solved cube looks like this:
-              *
-              * UF0 UB0 DB0 DF0 UR0 UL0 DL0 DR0 FR0 FL0 BL0 BR0
-              * UFR0 UBL0 DFL0 DBR0 UFL0 UBR0 DFR0 DBL0
-              *
-              * The cube after the moves R'U'F looks like this:
-              *
-              * FL1 BR0 DB0 UR1 UF0 UB0 DL0 FR0 UL1 DF1 BL0 DR0
-              * UBL1 DBR1 UFR2 DFR2 DFL2 UBL2 UFL2 DBL0
-              *
-              * Whitespace (including newlines) between pieces is ignored when
-              * reading the cube. A single whitespace character is added
-              * between pieces when writing.
-              */
-        SRC, /* The SRC format can be used to generate code for internal use.
-              *
-              * In cube.c, a type called cube_array_t is defined and used for
-              * basic, non-performance-critical methods. If OUT is the output
-              * in SRC format, the following line can be used to declare a new
-              * cube object:
-              *
-              * cube_array_t cube = OUT
-              */
-        AVX, /* The AVX format is analogous to SRC, but for the AVX2 internal
-              * representation of the cube.
-              */
-} format_t;
-
 /* Reads a cube from buf in the specified format, and return it.
- * Supported formats: H48.
+ * Supported formats: "H48".
  */
-cube_t readcube(format_t format, char *buf);
+cube_t readcube(char *format, char *buf);
 
 /* Write the given cube to buf in the specified format.
- * Supported formats: H48, SRC, AVX.
+ * Supported formats: "H48", "SRC", "AVX".
  */
-void writecube(format_t format, cube_t cube, char *buf);
-
-/* Utilities for reading and writing moves */
-int readmoves(char *buf, move_t *moves);
-void writemoves(move_t *moves, int n, char *buf);
-trans_t readtrans(char *buf);
-void writetrans(trans_t trans, char *buf);
+void writecube(char *format, cube_t cube, char *buf);
 
 /******************************************************************************
 Coordinates
 
-The coordinate functions compute one aspect of the cube (for example,
-the edge orientation) and they return it as an integer. They are used
-for example to build pruning tables for various solving methods.
+TODO description
 ******************************************************************************/
 
-int16_t coord_eo(cube_t); /* Edge orientation */
+int64_t coord_eo(cube_t);
 
 /******************************************************************************
 Solvers
 
-All solvers work at fixed depth, i.e. they will only find solutions of the
-specified length. Iterating over the possible lengths, if desired, is left as
-an implementation detail for the user of this library.
-
-The solutions are returned as a list of moves, which can then be converted to
-a string using writemoves().
+The solutions are returned as a newline-separated list of characters.
 
 Unless specified otherwise, all the solutions are not trivially simplifiable.
 This means that sequences like U U2 or R L R will not appear in any solution.
@@ -188,6 +130,7 @@ TODO NISS / INVERSE / LINEAR as a mask?
 
 All solvers take at least the following parameters, satisfying the conditions
 in square brackets:
+TODO more!
         - cube_t cube [issolvable(cube)]: The cube to solve.
         - uint8_t depth [depth <= 20]: The lenght of the solution.
         - int maxsols: The maximum number of solutions to find. The solver
@@ -201,12 +144,12 @@ in square brackets:
 Some solvers take other parameters. See below for details.
 ******************************************************************************/
 
+/* TODO
 int solve_generic(
         cube_t cube,
         uint8_t depth,
         int maxsols,
-        move_t *ret
-        int (*estimate)(cube_t),
+        uint8_t *ret, // TODO change to char
+        int (*estimate)(cube_t)
 );
-
-int solve_light(cube_t, int
+*/