VistaIOGetAttr(3)

💖 VistaIOGetAttr 💖

ok so bestie, we're in section 3 of the Library Functions Manual today and the vibe is immaculate — this is the VistaIOGetAttr page, aka the one where you finally learn how to snatch an attribute's value out of a list. let's go 🫶

---

✨ NAME ✨

VistaIOGetAttr, VistaIOGetAttrValue — fetch an attribute's value 🎀

---

🌸 SYNOPSIS 🌸

VistaIOGetAttrResult VistaIOGetAttr (list, name, dict, repn, value)
       VistaIOAttrList list;
       VistaIOStringConst name;
       VistaIODictEntry *dict;
       VistaIORepnKind repn;
       VistaIOPointer value;

typedef enum { VistaIOAttrFound, VistaIOAttrMissing, VistaIOAttrBadValue } VistaIOGetAttrResult;

VistaIOBoolean VistaIOGetAttrValue (posn, dict, repn, value)
       VistaIOAttrListPosn *posn;
       VistaIODictEntry *dict;
       VistaIORepnKind repn;
       VistaIOPointer value;

---

💅 ARGUMENTS 💅

• list — the list of attributes we're gonna search by name to find the one you want. it's giving directory energy 🔍
• name — the name of the attribute you're looking for. literally just the name. iconic.
• posn — where the desired attribute is chillin' inside its attribute list. it's the position, bestie 📍
• dict — may specify a dictionary used for recognizing a keyword that's stored as the attribute's value… or it can be NULL. your call, queen 👑
• repn — the representation you want the attribute value returned in. like, what form should it come back as? 🤔
• value — the location where the attribute value gets returned. this is where it lands, no cap 📬

---

🦋 DESCRIPTION 🦋

okay so both of these routines return an attribute's value, right? but the way they find the attribute is different, and that's the whole plot twist:

• VistaIOGetAttr fetches the value of the first attribute with the name name in the list list. 🔥
• VistaIOGetAttrValue fetches the value of the attribute whose position within an attribute list is posn. 💫

now here's the part where it gets juicy. if a dictionary, dict, has been provided and the attribute's value is stored as a character string, the routine checks whether that string is a keyword defined in the dictionary. if it is, it uses the value associated with that keyword instead of the attribute's original value. (peep the VistaIOdictionary(3) manual page for the tea ☕)

the value you get — whether it came directly from the attribute or indirectly via the dictionary — gets converted to the representation repn and then stored at the location pointed to by value. the repn argument may have any VistaIORepnKind value (like, any of the values returned by VistaIORegisterType(3)). however — and this is the catch, bestie — an attribute value that is a string can only be returned as a string or a number, and other attribute values can only be returned in the representation with which they are stored. (the VistaIOGetAttrRepn(3) macro can tell you an attribute value's representation if you're ever unsure 👀)

so about copying: if repn calls for a number to be returned, the caller receives a copy of the value stored with the attribute. if, on the other hand, it calls for a string, attribute list, pointer, image, edge set, etc., the caller receives a pointer to the same value as that stored with the attribute. same value, not a copy. noted. ✍️

---

🌈 RETURN VALUES 🌈

• if the specified attribute is not found, VistaIOGetAttr returns VistaIOAttrMissing. 😭
• if it is found but its value can't be converted to the desired representation, VistaIOGetAttr returns VistaIOAttrBadValue. 💀
• otherwise? VistaIOGetAttr is successful and returns VistaIOAttrFound, having stored the attribute's value at *value. slay ✨

and for the other one:

• VistaIOGetAttrValue returns TRUE if it's successfully returning the attribute's value at *value, and FALSE if the value can't be converted to the desired representation. simple as that 💖

---

🎀 EXAMPLES 🎀

okay this code fragment prints the name of an image, and honestly it eats:

VistaIOImage image;
VistaIOStringConst name;

if (VistaIOGetAttr (VistaIOImageAttrList (image), VistaIONameAttr, NULL,
       VistaIOStringRepn, (VistaIOPointer) & name) == VistaIOAttrFound)
       printf ("Name: %s\n", name);

---

⭐ SEE ALSO ⭐

VistaIOExtractAttr(3), VistaIOSetAttr(3), VistaIOSetAttrValue(3), VistaIOattribute(3), VistaIOdictionary(3),

---

🧚 NOTES 🧚

VistaIOGetAttr is meant for use with attribute lists representing sets, in which each attribute name occurs at most once. if list contains multiple attributes named name, only the first is located and returned. first come, first served, periodt 💅

the value argument must point to sufficient storage to contain a value of the representation requested. neither the routine nor the C compiler can automatically check that this is so. this is a you problem, bestie, and the compiler will not save you 🙈

---

👑 AUTHOR 👑

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

---

and that's the whole page, bestie 💜 this was VistaIO Version 1.2.14, dated 24 April 1993 — a whole vintage icon that's still serving looks. go forth and fetch those attributes, you've got this 🦋✨💖