Struct

IpuzEnumeration

Description [src]

struct IpuzEnumeration {
  /* No available fields */
}

An opaque, immutable data type that stores the enumeration of a clue.

Once created this structure will never change. As a result, it can be shared safely across different puzzles.

Context

In crosswords, the enumeration of a clue is a hint about the grid markings to be used with the answer. It can indicate punctuation, word breaks, or other display hints.

As an example, consider this clue from a puzzle:

1ac. Beginnings of an afternoon beard (5,1'5,6)

Here, the enumeration is represented by the string (5,1'5,6). It indicates the formatting of the answer — FIVE O'CLOCK SHADOW — and provides hints for rendering the grid to accommodate it.

Example rendering of FIVE O'CLOCK SHADOW Example rendering of FIVE O’CLOCK SHADOW

This enumeration was created by calling:

ipuz_enumeration_new ("5 1'5 6");

The enumeration string

The IpuzEnumeration expects to be passed a valid string as defined by the ipuz spec when it is created. Currently, word counts and prompts from the spec are not supported. The full set of punctuation characters supported can be seen in IpuzDeliminator.

If an IpuzEnumeration is created with an invalid string, then it won’t have any deliminators. You can use ipuz_enumeration_get_has_delim() to make sure the enumeration has been created correctly.

Display strings

If you want to represent the string to the user, you should use ipuz_enumeration_get_display(). One slightly confusing thing about enumerations this is that the string used to create the enumeration doesn’t match the output string for displaying to the user. Most notably, the spec uses spaces to indicate word breaks, which are represented by commas for the display string.

Here’s an example:

// This will create the enumeration represented in the example above
enumeration1 = ipuz_enumeration_new ("5 1'5 6", IPUZ_VERBOSITY_STANDARD);

// This will not parse correctly and will just display the raw string
enumeration2 = ipuz_enumeration_new ("5,1'5,6", IPUZ_VERBOSITY_STANDARD);

In this code example above, both enumeration1 and enumeration2 will output the same display string, but only the first can be used to calculate grid markings.

Delimiators and grid offsets

Enumerations use IpuzDeliminator to indicate what hint should be used for grid markings. Deliminators can mark both an edge between cells as well as the cell itself. See IpuzEnumerationForeachDelimFunc for more information on how to determine where it should apply.

Constructors

ipuz_enumeration_new

Creates a new enumeration based on src.

Functions

ipuz_enumeration_valid_char
No description available.

Instance methods

ipuz_enumeration_delim_length

Returns the length of enumeration in cells. As an example, an enumeration created by “4-4 3” would return a length of 11. A length of 0 indicates an indeterminate length. A length of -1 indicates that the source string for the enumeration wasn’t parseable.

ipuz_enumeration_equal

Compares two enumerations and returns TRUE if they are identical.

ipuz_enumeration_foreach_delim

Calls func for each deliminator in self.

ipuz_enumeration_get_display

Returns a string for displaying the user representing the enumeration. It does not include outer parens, so will need to be printed in them if appropriate.

ipuz_enumeration_get_has_delim

Returns whether self has valid delims within it. As an example, an enumeration created by “4-4 3” would return TRUE, while an enumeration of “two words” would return FALSE.

ipuz_enumeration_get_src

Returns a copy of the source string used to make self.

ipuz_enumeration_ref

Refs the enumeration.

ipuz_enumeration_unref

Unrefs self, which will be freed when the reference count becomes 0.