fm_select.h File Reference

One page of a folder held while the folder is read: which entries a bounded list keeps, in an order the caller names. More...

#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	fm_select_t
	One page being chosen while a folder is read. Filled by fm_select_begin(); the fields are the walk's, not the caller's. More...

Typedefs
typedef int(*)	fm_rank_fn(const void *a, const void *b)
	The order of two entries, as qsort() takes it.

Enumerations
enum	fm_page_dir_t { FM_PAGE_FROM = 0 , FM_PAGE_AFTER , FM_PAGE_BEFORE }
	Which side of the key a page holds. More...

Functions
int	fm_select_keep (void *set, size_t size, int count, int capacity, const void *cand, fm_rank_fn rank)
	Offer cand to a set of count entries in rank order, which keeps the capacity entries that rank first.
void	fm_select_begin (fm_select_t *sel, void *set, size_t size, int capacity, fm_rank_fn rank, fm_page_dir_t dir, const void *key)
	Start choosing one page into set.
void	fm_select_offer (fm_select_t *sel, const void *cand)
	Offer one entry of the folder.
int	fm_select_end (fm_select_t *sel, fm_rank_fn show, int *ahead)
	End the walk: sort the page for display and say where it stands.

Detailed Description

One page of a folder held while the folder is read: which entries a bounded list keeps, in an order the caller names.

A folder holds more entries than a page has room for, and a walk hands them over in the order the volume holds them, which is creation order and not the list's. So every entry is offered as it arrives, and the page keeps the ones on its side of a key: the first entries from the key on (FROM), the first after it (AFTER, the next page), or the last ahead of it (BEFORE, the page before). A key is an entry, the one at a page's edge, and not a page number: nothing about the other pages is held, and a key whose file has gone still names a place in the order. Memory is the page and nothing more: one walk per page, whatever the folder holds.

Entries are the caller's type, of any size, compared by a function of the caller's, as qsort() takes them. The order has to be strict, zero only for one entry: two entries that tie fall on the key's side of every page edge, and one of them is on no page. LOGS keeps its runs newest first (log_select.h, log_name_rank()); the file manager keeps folders first and names in order (fm_tree.h).

The offers may come in any order and from more than one walk of a folder: what a page holds depends on what was offered, not on when.

Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Typedef Documentation

fm_rank_fn

typedef int(*) fm_rank_fn(const void *a, const void *b)

The order of two entries, as qsort() takes it.

Parameters

a	an entry
b	an entry

Returns

negative when a ranks ahead, positive when b does, 0 for one entry

Enumeration Type Documentation

fm_page_dir_t

enum fm_page_dir_t

Which side of the key a page holds.

Enumerator
FM_PAGE_FROM	The first entries that rank with the key or behind it. With no key, the first page.
FM_PAGE_AFTER	The first entries that rank behind the key: the next page. With no key, the first page.
FM_PAGE_BEFORE	The last entries that rank ahead of the key: the page before. With no key, the last entries of all: the last page.

Function Documentation

fm_select_begin()

void fm_select_begin	(	fm_select_t *	sel,
		void *	set,
		size_t	size,
		int	capacity,
		fm_rank_fn	rank,
		fm_page_dir_t	dir,
		const void *	key )

Start choosing one page into set.

Parameters

sel	the walk's state
set	room for capacity entries of size bytes
size	bytes of one entry
capacity	entries set takes
rank	the order the pages run in; strict
dir	the side of key the page holds
key	the entry at the page's edge, or NULL for none; it has to outlive the walk

fm_select_end()

int fm_select_end	(	fm_select_t *	sel,
		fm_rank_fn	show,
		int *	ahead )

End the walk: sort the page for display and say where it stands.

Parameters

sel	the walk's state
show	the order the page is drawn in, or NULL for the walk's own order
ahead	takes the count of offered entries that rank ahead of the page's first; may be NULL

Returns

the entries the page holds

fm_select_keep()

int fm_select_keep	(	void *	set,
		size_t	size,
		int	count,
		int	capacity,
		const void *	cand,
		fm_rank_fn	rank )

Offer cand to a set of count entries in rank order, which keeps the capacity entries that rank first.

A candidate that ranks behind a full set is dropped; one that ranks ahead of its last entry takes that entry's place.

Parameters

set	the entries, in rank order
size	bytes of one entry
count	entries in set: the last call's answer
capacity	room in set
cand	the entry offered; copied when it is kept
rank	the order

Returns

the count after the offer; never above capacity

fm_select_offer()

void fm_select_offer	(	fm_select_t *	sel,
		const void *	cand )

Offer one entry of the folder.

Parameters

sel	the walk's state
cand	the entry; copied when it is kept