gd_nentries(3)

💖 gd_nentries(3) — GETDATA 💖

okay bestie, gather round, because today we are counting entries in a Dirfile and it is going to be so satisfying. this is gd_nentries(3), plus its whole little friend group: gd_nfields, gd_nfields_by_type, gd_nmfields, gd_nmfields_by_type, gd_nmvectors, and gd_nvectors. they all do basically the same thing and honestly? iconic of them.

---

✨ NAME ✨

gd_nentries, gd_nfields, gd_nfields_by_type, gd_nmfields, gd_nmfields_by_type, gd_nmvectors, gd_nvectors — count field entries in a Dirfile 🧮

---

🌸 SYNOPSIS 🌸

#include <getdata.h>

unsigned int gd_nentries(DIRFILE *dirfile, const char *parent, unsigned
       int type, unsigned int flags);

unsigned int gd_nfields(DIRFILE *dirfile);

unsigned int gd_nfields_by_type(DIRFILE *dirfile, gd_entype_t type);

unsigned int gd_nmfields(DIRFILE *dirfile, const char *parent);

unsigned int gd_nmfields_by_type(DIRFILE *dirfile, const char *parent,
       gd_entype_t type);

unsigned int gd_nmvectors(DIRFILE *dirfile, const char *parent);

unsigned int gd_nvectors(DIRFILE *dirfile);

---

🦋 DESCRIPTION 🦋

so. gd_nentries() looks at a dirfile(5) database — the one you handed over as dirfile — and counts how many metadata entries match whatever criteria you gave it. bestie it is literally a counter. it counts. that's the whole vibe. 💅

if parent is non-NULL, we're looking at the metafields hanging out underneath the field named by parent. if parent is NULL? top-level fields only, and metafields get ignored entirely. sorry metafields, not today. 🙈

the type argument should be one of these symbols, and it means "count this specific entry type":

• GD_BIT_ENTRY
• GD_CARRAY_ENTRY
• GD_CONST_ENTRY
• GD_DIVIDE_ENTRY
• GD_INDEX_ENTRY
• GD_INDIR_ENTRY
• GD_LINCOM_ENTRY
• GD_LINTERP_ENTRY
• GD_MPLEX_ENTRY
• GD_MULTIPLY_ENTRY
• GD_PHASE_ENTRY
• GD_POLYNOM_ENTRY
• GD_RAW_ENTRY
• GD_RECIP_ENTRY
• GD_SARRAY_ENTRY
• GD_SBIT_ENTRY
• GD_SINDIR_ENTRY
• GD_STRING_ENTRY
• GD_WINDOW_ENTRY

(GD_INDEX_ENTRY is a special field type for the implicit INDEX field, iykyk)

...or else it can be one of these special symbols instead:

• GD_ALL_ENTRIES (=0) — count entries of all types. everything. the whole buffet. 🍓
• GD_ALIAS_ENTRIES — count only aliases. and listen, this is the only way to get a count that includes aliases which don't point to valid field codes. noted. 💀
• GD_SCALAR_ENTRIES — count only scalar field types (CONST, CARRAY, SARRAY, STRING).
• GD_VECTOR_ENTRIES — count only numeric-valued vector field types (every field type except SINDIR and the scalar field types listed above).

then there's flags, which should be zero or more of these, bitwise or'd together:

• GD_ENTRIES_HIDDEN — include hidden entries (peep gd_hidden(3)) in the count: normally hidden entries get skipped. sneaky little things. 👀
• GD_ENTRIES_NOALIAS — exclude aliases from the count: normally aliases count the same as their target (so a field with n aliases, plus its canonical name, gets counted n+1 times). math is math. ✨

also just so you know: this function has a subset of the functionality of the gd_match_entries(3) function (q.v.). it's the chill younger sibling.

---

🎀 Special Cases 🎀

the call

gd_nfields(dirfile);

is equivalent to

gd_nentries(dirfile, NULL, GD_ALL_ENTRIES, 0);

the call

gd_nfields_by_type(dirfile, type);

is equivalent to

gd_nentries(dirfile, NULL, type, 0);

the call

gd_nmfields(dirfile, parent);

is equivalent to

gd_nentries(dirfile, parent, GD_ALL_ENTRIES, 0);

the call

gd_nmfields_by_type(dirfile, parent, type);

is equivalent to

gd_nentries(dirfile, parent, type, 0);

the call

gd_nmvectors(dirfile, parent);

is equivalent to

gd_nentries(dirfile, parent, GD_VECTOR_ENTRIES, 0);

the call

gd_nvectors(dirfile);

is equivalent to

gd_nentries(dirfile, NULL, GD_VECTOR_ENTRIES, 0);

---

👑 RETURN VALUE 👑

when everything goes right, these functions return an unsigned in (yes, the manpage says unsigned in, we are reporting the facts bestie, no edits 💖) telling you the number of entries in the database that satisfied your criteria. slay.

on error, they return zero and stash a negative-valued error code inside the DIRFILE object, which you can grab with a later call to gd_error(3). possible error codes are:

• GD_E_BAD_CODE — the parent field code you supplied was not found, or it referred to a metafield itself. 🚫
• GD_E_BAD_DIRFILE — the dirfile you supplied was invalid. not it. 😭
• GD_E_BAD_ENTRY — the type parameter you supplied wasn't one of the symbols listed above. wrong symbol, babe.

heads up: a descriptive error string for the error can be obtained by calling gd_error_string(3). use it, it's giving helpful. 🫶

---

🌈 HISTORY 🌈

• the get_nfields() function appeared in GetData-0.3.0.
• the get_nfields_by_type(), get_nmfields(), get_nmfields_by_type(), get_nmvectors(), and get_nvectors() functions appeared in GetData-0.4.0.
• in GetData-0.7.0, these functions were renamed to gd_nfields(), gd_nfields_by_type(), gd_nmfields(), gd_nmfields_by_type(), gd_nmvectors(), and gd_nvectors(). rebrand era. 💅
• the gd_nentries() function appeared in GetData-0.8.0.

---

🔥 SEE ALSO 🔥

dirfile(5), gd_open(3), gd_entry_list(3), gd_error(3), gd_error_string(3), gd_hidden(3), gd_match_entries(3)

---

and that's the whole page bestie!! Version 0.10.0, dated 25 December 2016 — a little holiday gift from the GETDATA era. go forth and count responsibly. mwah. 💖✨🎀