ARCHITECTURE.md

Architecture

This document aims to describe the file structure and contents of this project.

Root

The root directory contains the primary header files to define and implement iterators and iterator instances (i.e iterables)

File	Description
typeclass.h	Utility macros to define a typeclass and its instance.
maybe.h	Utility macros to define and use a Maybe type.
iterator.h	Primary file containing macros to define the Iterator typeclass, Iterable typeclass instance and a utility macro, impl_iterable, that defines a function to wrap a pointer type into an Iterable - essentially implementing the Iterator typeclass for that type.

Examples

The examples/ directory contains usage examples of the Iterator typeclass pattern.

This also contains a subdirectory - iterutils, which contains utilities to work with generic Iterables.

iterutils

File	Description
take.h	Macros to define an IterTake struct of a certain element type. This struct stores a source iterable, and keeps track of how many elements to extract from it. This is used to implement a take-like function. Defines a macro to implement Iterator for an IterTake struct, as well as a macro (take_from) to "take" n elements from a given iterable, lazily.
map.h	Macros to define an IterMap struct of a certain element and return type. This struct stores a source iterable, and a function to map over the iterable. Defines a macro to implement Iterator for an IterMap struct, as well as a macro (map_over) to map a function (fn) over a given iterable, lazily.
iterable_utils.h	Declarations of all the utility functions to be exposed to the examples.
iterable_utils.c	Definitions of the utility functions.

The usage of these iterutils and the primary header files are demonstrated by the files in examples/-

File	Description
func_iter.h	Includes all the primary headers from the root directory. Also defines Maybe and Iterator for the following types- int char* (Typedef-ed to string) uint32_t
examples.h	Declarations for all the functions demonstrating iterable usage.
main.c	The main function definition, executes the functions demonstrating iterable usage. (Declared in examples.h)
array_iterable.h	Declarations for functions and structs to be used to use an array as an Iterable. This defines the ArrIter struct - this struct wraps an array and has an Iterator implementation.
array_iterable.c	Definitons for functions be used to use an array as an Iterable. This implements the Iterator typeclass for the ArrIter struct.
list_iterable.h	Declarations for functions and structs to be used to use a singly linked list as an Iterable. This defines the ListIter struct - this struct wraps a singly linked list and has an Iterator implementation.
list_iterable.c	Definitons for functions to be used to use a singly linked list as an Iterable. This implements the Iterator typeclass for the ListIter struct.
fibonacci_iterable.h	Declarations for functions and structs to be used to use an Iterable representing the infinite fibonacci sequence.
fibonacci_iterable.c	Definitions for functions to be used to use an Iterable representing the infinite fibonacci sequence.
arr_to_iterble.c	Example function that wraps an array into an Iterable to be used by a generic function operating on iterables.
list_to_iterble.c	Example function that wraps a singly linked list into an Iterable to be used by a generic function operating on iterables.
list_from_arr.c	Example function that wraps an array into an Iterable that can be used to build a singly linked list from a generic function operating on iterables.
fibonacci.c	Example function that prints the elements from an Iterable representing the infinite fibonacci sequence.
map_over.c	Example usage of the map utility, that maps functions over an Iterable.