.\" "@(#)publib-tbuf:$Id: tbuf.3,v 1.2 2004/08/05 08:48:21 liw Exp $"
.TH TBUF 3
.SH NAME
tbuf_create,
tbuf_destroy,
tbuf_copy,
tbuf_cat,
tbuf_length,
tbuf_chars \- manipulate text editor buffer
.SH SYNOPSIS
.nf
.B #include <publib.h>
.sp
.BI "Tbuf *tbuf_create(const char *" chars ", size_t " len ");"
.BI "void tbuf_destroy(Tbuf *" tbuf ");"
.BI "Tbuf *tbuf_copy(Tbuf *" tbuf ", size_t " offset ", size_t" len ");"
.BI "Tbuf *tbuf_cat(Tbuf *" tbuf ", Tbuf * " tbuf ");"
.BI "size_t tbuf_length(Tbuf *" tbuf ");"
.BI "void tbuf_chars(char *" chars ", Tbuf *" tbuf ", size_t " offset ", size_t " len ");"
.fi
.SH DESCRIPTION

These routines create and manipulate simple text editor buffers,
which can also be thought of as arbitrarily large text strings.
The buffers are one-dimensional (i.e., not automatically divided into lines),
and are indexed with character offsets.
They are 8-bit and binary clean,
i.e., they may contain any 8-bit characters,
including the zero byte ('\\0').
.PP
.B tbuf_create
creates a buffer from a C character array,
and
.B tbuf_destroy
destroys
it.
Once it's created,
a buffer may not be modified.
Instead, a new buffer needs to be created,
using
.B tbuf_cat
and
.BR tbuf_copy .
They create the new buffer so that it shares as much memory as possible with
the old buffer,
so the immutability does not necessarily waste memory much.
By never changing a buffer,
it is rather simple to implement undo and redo:
you only need to keep a list of buffers and display the suitable one to the
user.
The caller should remember to call
.B tbuf_destroy
for unnecessary buffers,
of course.
.PP
.B tbuf_length
returns the number of characters in the buffer.
.B tbuf_copy
copies part of a buffer into a C character array.
The array is
.I not
zero-terminated;
the caller must do it himself.
.SH "RETURN VALUE"
.BR tbuf_create ,
.BR tbuf_copy ,
and
.B tbuf_cat
return a pointer to the new buffer,
or NULL if the operation failed.
.PP
.B tbuf_length
returns the number of characters in the buffer.
.PP
.B tbuf_destroy
and
.B tbuf_chars
return nothing and cannot fail.
.SH "SEE ALSO"
.BR publib "(3), " sbuf "(3)"
.SH AUTHOR
Lars Wirzenius, liw@iki.fi.