1# clib
 2
 3C implementations of performance-critical operations, integrated via [cgo](https://pkg.go.dev/cmd/cgo).
 4
 5## Why C?
 6
 7Some operations in Matcha benefit from dropping into C for speed and lower memory usage. The biggest wins are in image dimension queries (30,000x faster than Go's stdlib) and base64 wrapping for large attachments (3-4x faster).
 8
 9## Components
10
11### base64wrap
12
13MIME-compliant base64 line-wrapping (RFC 2045). Wraps base64-encoded strings at 76 characters with `\r\n` separators. Used by `sender/` for every attachment, inline image, and S/MIME signature.
14
15Files: `base64wrap.c`, `base64wrap.h`, `base64wrap.go`
16
17### imgconv
18
19Image decoding and PNG re-encoding using [stb_image](https://github.com/nothings/stb) (vendored single-header C libraries). No external system dependencies required.
20
21- `DecodeToPNG()` — decodes any image format (JPEG, PNG, BMP, GIF) and re-encodes to PNG. Used by `view/html.go` for inline email images.
22- `ImageDimensions()` — reads image width and height from the header only, without decoding pixel data. Used to calculate terminal row spacing for inline images.
23
24Files: `imgconv.c`, `imgconv.h`, `imgconv.go`, `stb_image.h`, `stb_image_write.h`
25
26
27## Adding new C code
28
291. Create `yourmodule.c` and `yourmodule.h` in this directory
302. Create `yourmodule.go` with cgo bindings (see `base64wrap.go` for a minimal example)
313. Add tests in `yourmodule_test.go`
324. If your C code uses `libm` or other system libraries, add `#cgo LDFLAGS: -lm` in the Go file