MST_FINDMATCH(3)

MST_FINDMATCH 💅

okay bestie, welcome to the MST_FINDMATCH(3) page — this is section 3 of the manual (library functions, the fun ones ✨), and it's literally all about hunting down the exact MSTrace you want inside a MSTraceGroup. no cap. let's go 🦋

---

✨ NAME ✨

mst_findmatch — searching a MSTraceGroup for specific MSTrace structures. it's giving "where's my trace" energy, and honestly? iconic.

---

✨ SYNOPSIS ✨

#include <libmseed.h>

MSTrace  *mst_findmatch ( MSTrace *startmst, char dataquality,
                          char *network, char *station,
                          char *location, char *channel );

MSTrace  *mst_findadjacent ( MSTraceGroup *mstg,
                             flag *whence, char dataquality,
                             char *network, char *station,
                             char *location, char *channel,
                             double samprate, double sampleratetol,
                             hptime_t starttime, hptime_t endtime,
                             double timetol);

like… two functions, one header, zero drama 💖

---

✨ DESCRIPTION ✨

the mst_findmatch of it all

so mst_findmatch traverses a MSTrace chain starting at startmst and returns the first entry that matches the source name identifiers. like it's just out here walking the linked list, matching vibes. 🚶‍♀️✨

and bestie, if dataquality is not zero, it has to match the found entry too. no exceptions, that's the rule. 👑

a calling program commonly calls this routine in a loop in order to find all matching MSTraces in a MSTraceGroup. so yes, the intended lifestyle is: loop it. periodt.

the mst_findadjacent of it all

mst_findadjacent finds the first entry in the MSTraceGroup pointed to by mstg that matches the given source name identifiers and is time adjacent to the time coverage described by the samprate, starttime and endtime. adjacent as in "right next to it", not adjacent as in "we sat next to each other in class once". 😌

again, if dataquality is not zero it must also match the found entry.

psst — see ms_time(3) for a description of the high precision epoch time format needed for starttime and endtime. don't skip that, fr fr. 📖

tolerances, aka how picky are we being

the tolerance for sample rate and time matching can also be specified. here's the tea: 🍵

• if sampratetol is -1.0 the default tolerance of abs(1-sr1/sr2) < 0.0001 is used.
• if timetol is -1.0 the default time tolerance of 1/2 the sample period will be used.
• if sampratetol or timetol is -2.0 the respective tolerance check will not be performed.
• if time tolerance is not checked, whence will be set to whichever end fits best.
• the time tolerance is specified in seconds. ⏱️

the whence flag moment 👑

when an adjacent MSTrace is found, the whence flag will be set to indicate where the indicated time span is adjacent, in the following way:

1. time span fits at the end of the MSTrace
2. time span fits at the beginning of the MSTrace

slay. two options. very demure. 🌸

---

✨ RETURN VALUES ✨

• mst_findmatch returns a pointer to the matching MSTrace structure — or 0 if no match found or error. 💀 (a 0 is not a vibe, but it is a valid answer.)
• mst_findadjacent returns a pointer to the adjacent MSTrace structure and the whence flag is set when an adjacent MSTrace is found — or 0 when no adjacent MSTrace is found.

---

✨ SEE ALSO ✨

ms_intro(3), mst_init(3) and ms_time(3). go read them, bestie, they're part of the friend group 🫶

---

✨ AUTHOR ✨

Chad Trabant IRIS Data Management Center

---

and that's the whole page, you ate it 💅✨

cute little sign-off for the receipts: this one's from the Libmseed API, dated 2006/02/27 — old but iconic, a true vintage. 🎀💖