Error Handling in libipuz

Error Handling in libipuz

libipuz reports three kinds of problems with a puzzle:

  1. Fatal Errors: No puzzle can be built. Loading returns NULL and sets a GError.
  2. Dropped Data: The puzzle loaded, but some of the file couldn’t be used.
  3. Puzzle Problems: The puzzle is valid, but something about it may need attention, such as a clue with no text.

Fatal Errors

Fatal Errors only occur when loading a puzzle.

If the file or stream can’t be read, you get the error from GLib unchanged. It will be GFileError when loading a file, or GIOErrorEnum when loading a stream. All other fatal errors are in the IpuzPuzzleError domain, with these codes, listed in the order a loader might hit them:

Code Meaning
INVALID_JSON The file isn’t valid JSON
INVALID_FILE Valid JSON, but not an ipuz file
WRONG_VERSION The file is an ipuz version we don’t support
UNSUPPORTED_KIND The file is a puzzle kind we don’t support
INVALID_STRUCTURE The file is missing something critical to build the puzzle

INVALID_STRUCTURE is for files we can’t build a puzzle from at all, such as a grid larger than IPUZ_GRID_MAX_SIZE.

Dropped Data

Dropped Data is used to indicate information that was in the file, but isn’t in the loaded puzzle. It’s recorded as IpuzPuzzleLoadFlags, read through ipuz_puzzle_info_get_load_flags(). The flags describe the file that was loaded, so they don’t change as the puzzle is edited. They are copied by ipuz_puzzle_deep_copy(), but not compared by ipuz_puzzle_equal().

Flag Cause
GRID_TRUNCATED Cells beyond the grid’s dimensions were dropped
CLUE_CELLS_DROPPED Clue cells outside the grid were dropped
KIND_IGNORED An unsupported kind was ignored in favor of another
VALUE_DROPPED A field had the wrong type, and was ignored

Puzzle Problems

Puzzle Problems are calculated from the puzzle’s current state, so they apply to puzzles built through the API as well as loaded ones.

These are reported as IpuzPuzzleProblems, read through ipuz_puzzle_info_get_problems(). A value of IPUZ_PUZZLE_PROBLEM_NONE means there’s nothing to warn about.

These flags describe the puzzle as it is rather than indicate an error. They’re sometimes intentional in the puzzles and can be displayed/played anyway, in a degraded fashion. Some puzzles, such as alphabetic crosswords, do these things on purpose. Other puzzles may have no solution but a checksum. Applications should display the puzzle anyway, and decide how to present each problem.

Flag Cause
NO_SOLUTION A guessable cell has no solution
NOTHING_TO_GUESS There are no guessable cells
EMPTY_CLUE_TEXT A clue has no text
CLUE_WITHOUT_CELLS A clue has no cells
CELL_WITHOUT_CLUE A guessable cell isn’t part of any clue

A guessable cell is a normal cell without an initial value.

Note

Puzzle problems are separate from IpuzPuzzleFlags, which describe what the puzzle contains. In particular, IPUZ_PUZZLE_FLAG_HAS_SOLUTION means the loaded file had a solution, and doesn’t change after loading. IPUZ_PUZZLE_PROBLEM_NO_SOLUTION checks every guessable cell in the current puzzle, so a puzzle can have both if its solution has gaps.