qlibs:(scan)

✨ scan — string to integer conversion ✨

okay so this is the scan page from qlibs (that's the manual name, bestie, it's in the (scan) section if you're keeping score) and honestly? it's giving "tiny functions that do one thing and do it well" 💅 let's get into it.

---

🌸 NAME 🌸

scan — string to integer conversion. that's it. that's the whole vibe. turning your little text digits into actual numbers 🫶

---

🎀 SYNTAX 🎀

#include "scan.h"

unsigned int scan_8long(const char *src,unsigned long *dest);
unsigned int scan_uint(const char *src,int *dest);
unsigned int scan_long(const char *src,long *dest);
unsigned int scan_ulong(const char *src,unsigned long *dest);
unsigned int scan_xint(const char *src,int *dest);
unsigned int scan_xlong(const char *src,unsigned long *dest);

six functions, one header, all of them hand you back the number of bytes they chewed through. iconic behavior ✨

---

💖 DESCRIPTION 💖

okay so every single one of these cuties takes src, parses whatever number situation is living in there, drops the result in dest, and returns the number of bytes read from src. that return value is your bestie fr — it tells you where the number ended and everything else began 🦋

• scan_8long — parses an unsigned long integer in octal ASCII representation from src and writes the result into dest. returns the number of bytes read from src.
• scan_uint — parses an unsigned integer in decimal ASCII representation from src and writes the result into dest. returns the number of bytes read from src.
• scan_ulong — parses an unsigned long integer in decimal ASCII representation from src and writes the result into dest, and yes, returns the number of bytes read from src. this one has rules, bestie, so listen up:
  • leading + or - or space (or literally anything outside of 0-9) is not accepted. not even a little.
  • the libc conventions of "023" for octal or "0x23" for hexadecimal are not supported. none of that.
  • scan_ulong will abort the scan if the next character is not a digit, or if it is a digit but adding it to the number would lead to an integer overflow. it's protecting you 💀
  • scan_ulong returns the number of characters successfully scanned and processed from src.
• scan_long — same logic as scan_ulong, but now on a signed long integer in decimal ASCII format, and it does recognize the leading + or - sign. the glow-up 🫶
• scan_xint — parses an unsigned integer in hexadecimal ASCII representation from src and writes the result into dest. returns the number of bytes read from src.
• scan_xlong — parses an unsigned long integer in hexadecimal ASCII representation from src and writes the result into dest. returns the number of bytes read from src. it understands both upper and lower case letters 😌 but it does not expect or understand a "0x" prefix — so don't bring one, it's not that kind of party 🙈

---

🧚 GENERICS 🧚

so for the scan functions with decimal input — scan_uint, scan_ulong and scan_int als well scan_ulong — you can use the Generic scan_dnum 💫 and for scan_xint and scan_xlong there's the Generic scan_xnum.

why do you care? because this helps to avoid cases where the input is given as an alias. and the best part: generics are evaluated at compile time, so they don't impact execution performance at all. free real estate, no cap 🔥

---

🔥 EXAMPLES 🔥

here's where it gets good, watch:

scan_ulong("23",&i) => i=23, return 2

scan_ulong("+23",&i) => return 0

scan_ulong("-23",&i) => return 0

scan_ulong(" 23",&i) => return 0

no signs, no spaces. we don't do that here 💅

scan_ulong("23,42",&i) => i=23, return 2

see how the return value is your map? it stopped at the comma 🗺️

scan_ulong("023",&i) => i=23, return 3

not octal. just 23. read all three characters though ⭐

scan_ulong("0x23",&i) => i=0, return 1

it grabbed the 0 and immediately clocked out. 0x23 is not the moment 💀

scan_ulong("4294967296",&i) => i=429496729, return 9 // 32-bit system

overflow guard kicked in, stopped at 9 characters. she's got boundaries 😭

---

🌈 SEE ALSO 🌈

case(3), byte(3) — go say hi to the neighbors 🫶

---

and that's the page!! brought to you by the 3 crew of qlibs (scan), so go forth and parse responsibly, bestie 👑💜