ARIF_CTX_CREATE(3)

📦 version 0.3.0, in alpine 3.24

💅 ARIF_CTX_CREATE(3) — your girl's guide to making an input context ✨

(this is one of the ARIF User Manual pages, and yes bestie, it's about version 0.1.0 — more on that at the very bottom 🎀)

✨ NAME ✨

arif_ctx_create — okay so this is the one that creates an input context. iconic behaviour honestly 🫶

🌸 SYNOPSIS 🌸

#include <arif.h>

struct arif_ctx *
arif_ctx_create (
    struct arif_opts const *options
);

🦋 DESCRIPTION 🦋

So arif_ctx_create() makes you an input context, with options, like a little custom-built ✨situation✨ for your input. And the best part? Operations on separate input contexts totally do not affect each other. They're independent. They don't gossip. main character energy only 💅

But listen — when your input context is no longer in use, you gotta destroy it with arif_ctx_destroy(3). Don't just leave it lying around, that's so not slay of you 😭

🎀 Options 🎀

The struct arif_opts type is literally defined as:

struct arif_opts {
    arif_cand_disp_func *disp_cand;
    int                  page_size;
};
  • disp_cand — this member is the function that generates the text to display for a given candidate. And if it's NULL? No stress, a default function gets used instead, and what it does is prepend a bracket-enclosed index number to the text. Cute, right? 🍓
  • page_size — this member is literally just the number of candidates per page. that's it. that's the whole vibe ✨

💜 Candidate display function 💜

The arif_cand_disp_func type is defined as:

typedef char *(arif_cand_disp_func) (
    char const *text,
    int         text_len,
    char const *comment,
    int         comment_len,
    int         idx,
    int        *display_len_ptr
);

Let's break down these arguments, bestie, one by one 👑

  • text — the candidate's text, like, the thing that's gonna replace the original text. And len is its length in bytes. 📏
  • comment — if this one is not NULL, it contains descriptive text regarding the candidate. And argument comment_len is its length in bytes. 🗒️
  • idx — the candidate's index for the current page, and it starts at 1 (not 0, we're not doing that here, iykyk). 🔢

And what should your function actually do? It should return a malloc(3)'ed pointer to the text to display for the candidate — yes, malloc(3), that's on you, nobody's doing it for you — and store its length (in bytes) into display_len_ptr. Don't forget that part, that's the whole assignment 😤

🔥 RETURN VALUES 🔥

It returns an opaque pointer to the new input context. And it is guaranteed not to be NULL. Not even once. no cap. 🫶✨

Copyright (C) 2023 CismonX <admin@cismon.net>

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.

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.

fr fr go read the license, it's giving "required reading" but make it legal 💀

🌈 SEE ALSO 🌈

okay that's the whole page, you ate that 💖 version 0.1.0, dated Jan 02, 2023 — now go forth and create some contexts, bestie 🎀🦋✨

📦 where this page comes from