fm_select.c File Reference

Keeping the page a bounded list shows while a folder is read, in the caller's order (fm_select.h). More...

#include "fm_select.h"
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>

Functions
static void *	at (void *set, size_t size, int i)
	Entry i of set.
static int	order (fm_rank_fn rank, const void *a, const void *b)
	rank's answer as -1, 0 or 1, so that a sign can turn it round whatever its size.
static int	keep_ranked (void *set, size_t size, int count, int capacity, const void *cand, fm_rank_fn rank, int sign)
	The insertion both kinds of page share: sign 1 keeps the entries that rank first, -1 the entries that rank last.
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

Keeping the page a bounded list shows while a folder is read, in the caller's order (fm_select.h).

SPDX-License-Identifier: MIT

Function Documentation

at()

void * at ( void * set, size_t size, int i )

static

Entry i of set.

Parameters

set	the entries
size	bytes of one entry
i	the index

Returns

its address

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

keep_ranked()

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

static

The insertion both kinds of page share: sign 1 keeps the entries that rank first, -1 the entries that rank last.

Parameters

set	the entries, in sign times rank order
size	bytes of one entry
count	entries in set
capacity	room in set
cand	the entry offered
rank	the order
sign	1 or -1

Returns

the count after the offer

order()

int order ( fm_rank_fn rank, const void * a, const void * b )

static

rank's answer as -1, 0 or 1, so that a sign can turn it round whatever its size.

Parameters

rank	the order
a	an entry
b	an entry

Returns

-1, 0 or 1