Use a single Buffer type

[dfrg]

This removes GlyphBuffer and UnicodeBuffer, replacing them with a single Buffer type to more closely match HB.

Pros:

• Closer to HB API
• Don't need to use Option<UnicodeBuffer> and take() to reuse buffers
• Possible to make an HB compatible FFI without copies
• Enable support for HB style tracing messages (Add tracing messages #280)
• Toward support for WASM shaping in a separate crate (Export for GlyphExtents and UnicodeBuffer internals #91)
• Trivial to build the GlyphBuffer/UnicodeBuffer API on top

Cons:

• Larger number of methods so proper usage is less discoverable
• More methods are now fallible since they depend on the current content type

TODOs:

• Probably missed some content type checks but I think I found the important ones
• Replace asserts with errors... deferring since this PR is already large enough

[behdad]

LGTM with one comment inline. I'll comment separately on the assert vs error.

[behdad]

HarfBuzz also has a content type Invalid. That's used when you reset the buffer. Lemme see how you handle that...

[behdad]

Oh I see, you use an Option of it. I think that works.

[dfrg]

Yeah, this is simply more idiomatic when dealing with enums that have some sort of invalid state. We should probably do the same for the others.

[behdad]

This function should be renamed to push_char or something. Otherwise it's hard to differentiate it from add.

[dfrg]

While making changes, I took the opportunity to align this naming with the methods on the standard String type (I think we did the same when we renamed ensure -> reserve and other methods like push_str already match). I think this is the only caller for add so I can just inline the code to avoid confusion.

[behdad]

We want to keep add(), for lowlevel buffer work.

[behdad]

• Probably missed some content type checks but I think I found the important ones

Actually now I see a missing check in guess_segment_properties as well. HB has assert_unicode there.

• Replace asserts with errors... deferring since this PR is already large enough

I'm a proponent of assert / panic as these are preconditions. Errors that can never happen in correctly-constructed code end up just polluting the code IMO.

[rsheeter]

Errors that can never happen in correctly-constructed code end up just polluting the code IMO.

Making apis look infallible when they are fallible is hostile and violates the expectation that if your Rust code compiles it's likely to work.

Ideally we would structure the types so the error can't happen - nice if possible - so we don't need assert. If not then the failure is a valid outcome and Error seems correct, the user gets to decide what to do if they held it wrong and is made explicitly aware that it's possible to hold it wrong.

[behdad]

Making apis look infallible when they are fallible is hostile and violates the expectation that if your Rust code compiles it's likely to work.

So.. you don't believe in invariants, then?

[behdad]

Ideally we would structure the types so the error can't happen - nice if possible - so we don't need assert. If not then the failure is a valid outcome and Error seems correct, the user gets to decide what to do if they held it wrong and is made explicitly aware that it's possible to hold it wrong.

To me, this just shifts the problem to the user, since in a correct program they'd end up just unwraping, panicing, or ignoring the error. It is useful only when one is writing the program. To normal runs of the program it's just more nuisance in the client code all over.

[rsheeter]

I believe in invariants and prefer my invariants to be encoded in the type system / enforced by the compiler. If we can't do that here for some reason then just admit it, return a Result. The user will have another ? In their code, it's fine. Panics can change the impact from bad request to a downed job. Imagine a world where a lot of libraries chose to intake bad inputs and panic on them. It would *suck*, having Result where error is possible is dramatically better. Making the user handle more error conditions is something Rust gets right IMHO.

…

On Wed, Nov 12, 2025, 6:59 PM Behdad Esfahbod ***@***.***> wrote: *behdad* left a comment (harfbuzz/harfrust#298) <#298 (comment)> Ideally we would structure the types so the error can't happen - nice if possible - so we don't need assert. If not then the failure is a valid outcome and Error seems correct, the user gets to decide what to do if they held it wrong and is made explicitly aware that it's possible to hold it wrong. To me, this just shifts the problem to the user, since in a correct program they'd end up just unwraping, panicing, or ignoring the error. It is useful only when one is *writing* the program. To normal runs of the program it's just more nuisance in the client code all over. — Reply to this email directly, view it on GitHub <#298 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABRKXADPVVJFXOSSKA3HTN334PXXRAVCNFSM6AAAAACL52RO2WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKMRUHE3TMNRSHE> . You are receiving this because you commented.Message ID: ***@***.***>

[dfrg]

Actually now I see a missing check in guess_segment_properties as well. HB has assert_unicode there.

Ah, good catch, thanks.

[dfrg]

I can appreciate fail-fast error handling but our attitude toward this in Rust code so far has been to avoid panics except for the occasional internal invariant that we feel certain we've checked elsewhere. Note that Rust std does have some methods that panic but they're almost always accompanied by companion methods that return option or result.

I image there are ways to keep most of the benefits of this change while also using the type system to check some invariants. For example, something like:

// or BufferFillMode::Append which would clear the buffer only if it currently contains glyphs
buffer.fill(BufferFillMode::Replace).push_str("hello");

I'm not sure what to do about segment properties. Having them attached to the buffer means that they can always be unset or disagree with the requested shape plan. Making them required configuration rather than buffer properties solves this but takes us even further from HB.