.\"   Part of publib.
.\"  
.\"   Copyright (c) 1994-2006 Lars Wirzenius.  All rights reserved.
.\"  
.\"   Redistribution and use in source and binary forms, with or without
.\"   modification, are permitted provided that the following conditions
.\"   are met:
.\"  
.\"   1. Redistributions of source code must retain the above copyright
.\"      notice, this list of conditions and the following disclaimer.
.\"  
.\"   2. Redistributions in binary form must reproduce the above
.\"      copyright notice, this list of conditions and the following
.\"      disclaimer in the documentation and/or other materials provided
.\"      with the distribution.
.\"  
.\"   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
.\"   OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\"   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\"   ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
.\"   DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\"   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\"   GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\"   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\"   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\"   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\"   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"  
.\" "@(#)publib-tbuf:$Id: tbuf.3,v 1.2 2004/08/05 08:48:21 liw Exp $"
.TH TBUF 3pub
.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.