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
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.
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_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.