alphabet_soup.h File Reference

Word search puzzle solver API and bounded workspace definitions. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_io_stream.h"

Include dependency graph for alphabet_soup.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	soup_grid_t
	In-memory word search board matrix. More...
struct	soup_context_t
	Caller-owned bounded workspace for puzzle solving (zero-heap). More...

Enumerations
enum	soup_limits_t : uint32_t {   k_soup_max_grid_rows = 128U ,   k_soup_max_grid_cols = 128U ,   k_soup_max_word_chars = 128U ,   k_soup_max_file_capacity = 65536U ,   k_soup_max_parse_steps = 65536U ,   k_soup_max_line_steps = 1024U ,   k_soup_max_dim_digits = 8U ,   k_soup_direction_count = 8U }
	Fixed sizing and bounds for Alphabet Soup word search solver. More...

Functions
ra8_err_t	soup_init (soup_context_t *ctx)
	Initialize a caller-owned puzzle solver context.
bool	soup_find_word (const soup_grid_t *grid, const char *search_key, uint32_t key_len, uint32_t *out_start_row, uint32_t *out_start_col, uint32_t *out_end_row, uint32_t *out_end_col)
	Search a grid for a normalized word along all 8 compass directions.
ra8_err_t	soup_solve (soup_context_t *ctx, const char *text, uint32_t text_len, ra8_io_stream_t *out_stream)
	Parse board and words from puzzle text and emit solutions to the output stream.

Detailed Description

Word search puzzle solver API and bounded workspace definitions.

Tag

[Ring 4 / App] {World: Host}

Declares data structures and solver routines for parsing word search character grids and locating words along 8-way directional rays (horizontal, vertical, diagonal, forward, and backward) with strict bounds checking and zero dynamic allocation.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file alphabet_soup.h.

Enumeration Type Documentation

soup_limits_t

enum soup_limits_t : uint32_t

Fixed sizing and bounds for Alphabet Soup word search solver.

Enumerator
k_soup_max_grid_rows	Maximum board row dimension.
k_soup_max_grid_cols	Maximum board column dimension.
k_soup_max_word_chars	Maximum characters per target word.
k_soup_max_file_capacity	Maximum supported puzzle file size.
k_soup_max_parse_steps	Upper bound on file parse iterations.
k_soup_max_line_steps	Upper bound on line parse iterations.
k_soup_max_dim_digits	Maximum digits in dimension specifier.
k_soup_direction_count	8-way directional navigation rays.

Definition at line 28 of file alphabet_soup.h.

Function Documentation

soup_find_word()

bool soup_find_word ( const soup_grid_t * grid, const char * search_key, uint32_t key_len, uint32_t * out_start_row, uint32_t * out_start_col, uint32_t * out_end_row, uint32_t * out_end_col )

nodiscard

Search a grid for a normalized word along all 8 compass directions.

Parameters

[in]	grid	Pointer to populated board.
[in]	search_key	Normalized uppercase/stripped word string.
[in]	key_len	Length of normalized word.
[out]	out_start_row	Start row coordinate.
[out]	out_start_col	Start column coordinate.
[out]	out_end_row	End row coordinate.
[out]	out_end_col	End column coordinate.

Returns

bool True if word was found, false otherwise.

Precondition

grid, search_key, out_start_row, out_start_col, out_end_row, out_end_col are non-null.

key_len > 0.

Postcondition

Coordinates populated when true is returned.

Note

First-character candidate filtering provides optimal zero-allocation embedded search efficiency. For dynamic systems with massive dictionaries (10,000+ words), a multi-string Trie / Aho-Corasick automaton would be asymptotically preferred.

Since

0.1.0

Definition at line 162 of file alphabet_soup.c.

References soup_grid_t::cells, soup_grid_t::col_count, internal_check_cell(), k_soup_max_grid_cols, k_soup_max_grid_rows, k_soup_max_word_chars, and soup_grid_t::row_count.

Referenced by internal_solve_words().

soup_init()

ra8_err_t soup_init ( soup_context_t * ctx )

nodiscard

Initialize a caller-owned puzzle solver context.

Parameters

[out]

ctx

Solver context to zero-initialize.

Returns

ra8_err_t Result status.

Return values

k_ra8_ok	Context initialized.
k_ra8_err_null_ptr	ctx was null.

Precondition

ctx is non-null.

Postcondition

ctx is zero-initialized and ready for use.

Since

0.1.0

Definition at line 42 of file alphabet_soup.c.

References k_ra8_err_null_ptr, k_ra8_ok, and memset().

Referenced by soup_solve().

soup_solve()

ra8_err_t soup_solve ( soup_context_t * ctx, const char * text, uint32_t text_len, ra8_io_stream_t * out_stream )

nodiscard

Parse board and words from puzzle text and emit solutions to the output stream.

Parameters

[in,out]	ctx	Caller-owned solver context.
[in]	text	Null-terminated input file content.
[in]	text_len	Byte length of text.
[in,out]	out_stream	Bound destination stream for answer key emission.

Returns

ra8_err_t Status of parsing and emission.

Return values

k_ra8_ok	Puzzle parsed and output emitted.
k_ra8_err_null_ptr	A required pointer was null.
k_ra8_err_invalid_size	Text exceeded bounds or invalid dimensions.
k_ra8_err_range_check_failed	Dimensions or coordinates out of range.

Precondition

ctx, text, out_stream are non-null.

text_len <= k_soup_max_file_capacity.

out_stream is initialized and writable.

Postcondition

Answer key lines are written and flushed to out_stream.

Since

0.1.0

Definition at line 582 of file alphabet_soup.c.

References soup_grid_t::col_count, soup_context_t::grid, internal_parse_dimensions(), internal_parse_grid(), internal_solve_words(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_soup_max_file_capacity, soup_grid_t::row_count, and soup_init().

Referenced by main().