clib

README

clib

C implementations of performance-critical operations, integrated via cgo.

Why C?

Some 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).

Components

base64wrap

MIME-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.

Files: base64wrap.c, base64wrap.h, base64wrap.go

imgconv

Image decoding and PNG re-encoding using stb_image (vendored single-header C libraries). No external system dependencies required.

• DecodeToPNG() — decodes any image format (JPEG, PNG, BMP, GIF) and re-encodes to PNG. Used by view/html.go for inline email images.
• ImageDimensions() — reads image width and height from the header only, without decoding pixel data. Used to calculate terminal row spacing for inline images.

Files: imgconv.c, imgconv.h, imgconv.go, stb_image.h, stb_image_write.h

Adding new C code

1. Create yourmodule.c and yourmodule.h in this directory
2. Create yourmodule.go with cgo bindings (see base64wrap.go for a minimal example)
3. Add tests in yourmodule_test.go
4. If your C code uses libm or other system libraries, add #cgo LDFLAGS: -lm in the Go file

Documentation

Index

• Constants
• func ImageDimensions(data []byte) (width, height int, ok bool)
• func MarkdownToHTML(md []byte) []byte
• func WrapBase64(data string) string
• type HTMLElement
  • func HTMLToElements(html string) ([]HTMLElement, bool)
• type ImageConvertResult
  • func DecodeToPNG(data []byte) (ImageConvertResult, bool)

Constants

const (
	HElemText       = 0
	HElemH1         = 1
	HElemH2         = 2
	HElemLink       = 3
	HElemImage      = 4
	HElemBlockquote = 5
	HElemTable      = 6
)

HTMLElementType constants mirror the C enum values in htmlconv.h.

Functions

func ImageDimensions

func ImageDimensions(data []byte) (width, height int, ok bool)

ImageDimensions returns the width and height of an image without fully decoding pixel data. This is faster than DecodeToPNG when you only need the dimensions (e.g. to calculate terminal row count).

func MarkdownToHTML

func MarkdownToHTML(md []byte) []byte

MarkdownToHTML converts Markdown bytes to HTML using md4c (C). This is significantly faster than goldmark for large documents.

func WrapBase64

func WrapBase64(data string) string

WrapBase64 wraps base64-encoded data at 76 characters per line with \r\n separators, as required by MIME (RFC 2045).

Types

type HTMLElement

type HTMLElement struct {
	Type  int
	Text  string // Text content
	Attr1 string // href (link), src (image), cite (blockquote)
	Attr2 string // alt (image), prev_text (blockquote)
}

HTMLElement represents a parsed element from an HTML document.

func HTMLToElements

func HTMLToElements(html string) ([]HTMLElement, bool)

HTMLToElements parses HTML and returns structured elements. This is a single-pass C parser that replaces goquery-based DOM parsing.

type ImageConvertResult

type ImageConvertResult struct {
	PNGData []byte
	Width   int
	Height  int
}

ImageConvertResult holds the output of DecodeToPNG.

func DecodeToPNG

func DecodeToPNG(data []byte) (ImageConvertResult, bool)

DecodeToPNG takes raw image bytes (JPEG, PNG, BMP, GIF, etc.) and returns PNG-encoded bytes along with image dimensions. Uses stb_image for decoding and stb_image_write for PNG encoding in C, which is faster than Go's image stdlib for large images.