MST_CONVERTSAMPLES(3)

📦 version 2.19.8, in debian bookworm, debian trixie, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 MST_CONVERTSAMPLES(3) 💖

okay bestie, welcome to the Library Functions Manual entry for MST_CONVERTSAMPLES(3) — yes that's the header, yes it's giving very official, no we are not being boring about it 🌸

✨ NAME ✨

mst_convertsamples — glow-up your data samples by converting them between numeric types 💅

🎀 SYNOPSIS 🎀

#include <libmseed.h>

int  mst_convertsamples ( MSTrace *mst, char type, flag truncate);

int  mstl_convertsamples ( MSTraceSeg *seg, char type, flag truncate);

🦋 DESCRIPTION 🦋

so mst_convertsamples and mstl_convertsamples (the manual literally says mst_convertsamples twice, bestie, that's a lil typo — the second one is the mstl_ one up in the synopsis, we move on 💀) will take any data samples chillin' on an MSTrace or an MSTraceSeg and convert them to a type you specify. main character energy only.

the routines can convert between these three:

  • 32-bit integers — type i
  • 32-bit floats — type f
  • 64-bit doubles — type d

🌈 the rounding situation

when you're converting float and double sample types to integer type, a simple rounding gets applied: it adds 0.5 to the sample value before converting (truncating) it to an integer. why tho? because machines are messy and this compensates for common machine representations of floating point values — like how "40.0" might actually be living its life as "39.99999999". not her fault, she's doing her best 😭

💀 the truncate flag, pay attention

  • if the truncate flag is true, data samples get truncated to integers even if loss of sample precision is detected. no thoughts, head empty, we're going anyway.
  • if the truncate flag is false (0) and loss of precision is detected, an error is returned. she said absolutely not.

loss of precision is determined by testing that the difference between the floating point value and the (truncated) integer value is greater than 0.000001.

🚫 ascii girlies

ASCII data samples (type a) cannot be converted. if supplied or requested, an error will be returned. that's it, that's the whole thing, type a is not invited to this party 🙈

⭐ RETURN VALUES ⭐

mst_convertsamples and mstl_convertsamples return 0 on success and -1 on error. that's the vibe check: 0 = slay, -1 = not slay 🔥

👑 SEE ALSO 👑

ms_intro(3). go read her, she's iconic 💜

🌸 AUTHOR 🌸

Chad Trabant IRIS Data Management Center

no cap, this whole thing is the Libmseed API, dated 2013/10/01, and it's filed under MST_CONVERTSAMPLES(3). periodt. 🫶✨
📦 where this page comes from