.TH ARIF_FETCH 3 "Jan 02, 2023" 0.1.0 "ARIF User Manual"
.
.SH NAME
arif_fetch - fetch candidates
.
.SH SYNOPSIS
.EX
.B #include <arif.h>
.PP
.B int
.B arif_fetch (
.BI "    struct arif_ctx         *" ctx ,
.BI "    struct arif_cand const **" candidates_ptr
.B );
.EE
.
.SH DESCRIPTION
The
.BR arif_fetch ()
function fetches all candidates from the current page of input context
.I ctx
into an array of
.BR "struct arif_cand" ,
and stores a pointer to that array into
.IR candidates_ptr .
The array is valid until the next time
.BR arif_query ()
is called with new input text.
.SS Candidates
A candidate is a piece of text generated by an IME that is meant to replace
part of the original input text.
.PP
The
.B struct arif_cand
type is defined as:
.PP
.in +4n
.EX
struct arif_cand {
    char const *text;
    int         text_len;
    int         replace_start;
    int         replace_len;
    char const *transform;
    int         transform_len;
    char const *display;
    int         display_len;
};
.EE
.in
.PP
The
.I text
member is the actual text of the candidate, and
.I len
is its length in bytes.
.PP
Member
.I replace_len
is the number of leading bytes of the original text that are meant to
be replaced by the candidate, starting from byte offset
.IR replace_start .
.PP
Should the original text passed to
.BR arif_query ()
be transformed into another text when selecting this candidate, the resulting
text is put into
.IR transform ,
and
.I transform_len
is its length in bytes.
Otherwise,
.I transform
value is NULL.
.PP
The
.I display
member is the text to display when listing candidates for the user to choose.
Member
.I display_len
is its length in bytes.
.
.SH RETURN VALUES
Returns the number of items in the array stored to
.IR candidates_ptr .
.
.SH COPYRIGHT
Copyright (C) 2023  CismonX <admin@cismon.net>
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.PP
You should have received a copy of the license along with this document.
If not, see <https://www.gnu.org/licenses/fdl-1.3.html>.
.
.SH SEE ALSO
.BR arif_query (3),
.BR arif_select_page (3)