.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: ds
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Library Functions Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DS" "3" "02/19/2019" "DACS 1.4.40" "DACS Library Functions Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ds \- Dynamic strings and vectors
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include "dsslib\&.h"
.fi
.ft
.HP \w'Ds\ *ds_init('u
.BI "Ds *ds_init(Ds\ *" "ods" ");"
.HP \w'Ds\ *ds_init_size('u
.BI "Ds *ds_init_size(Ds\ *" "ods" ", size_t\ " "nbytes" ");"
.HP \w'Ds\ *ds_alloc('u
.BI "Ds *ds_alloc(void);"
.HP \w'Ds\ *ds_alloc_size('u
.BI "Ds *ds_alloc_size(size_t\ " "nbytes" ");"
.HP \w'Ds\ *ds_reinit('u
.BI "Ds *ds_reinit(Ds\ *" "ds" ");"
.HP \w'Ds\ *ds_reinit_size('u
.BI "Ds *ds_reinit_size(Ds\ *" "ods" ", size_t\ " "nbytes" ");"
.HP \w'Ds\ *ds_reset('u
.BI "Ds *ds_reset(Ds\ *" "ds" ");"
.HP \w'Ds\ *ds_reset_buf('u
.BI "Ds *ds_reset_buf(Ds\ *" "ds" ");"
.HP \w'Ds\ *ds_trim('u
.BI "Ds *ds_trim(Ds\ *" "ds" ");"
.HP \w'Ds\ *ds_grow('u
.BI "Ds *ds_grow(Ds\ *" "ds" ");"
.HP \w'void\ ds_free('u
.BI "void ds_free(Ds\ *" "ds" ");"
.HP \w'int\ ds_appendc('u
.BI "int ds_appendc(Ds\ *" "ds" ", int\ " "ch" ");"
.HP \w'int\ ds_copyb('u
.BI "int ds_copyb(Ds\ *" "ds" ", void\ *" "src" ", size_t\ " "len" ", unsigned\ int\ " "offset" ");"
.HP \w'int\ ds_insertb('u
.BI "int ds_insertb(Ds\ *" "ds" ", void\ *" "src" ", size_t\ " "len" ", unsigned\ int\ " "offset" ");"
.HP \w'int\ ds_append('u
.BI "int ds_append(Ds\ *" "ds" ", char\ *" "str" ");"
.HP \w'int\ ds_concat('u
.BI "int ds_concat(Ds\ *" "ds" ", char\ *" "str" ");"
.HP \w'int\ ds_concatc('u
.BI "int ds_concatc(Ds\ *" "ds" ", int\ " "ch" ");"
.HP \w'int\ ds_concatn('u
.BI "int ds_concatn(Ds\ *" "ds" ", char\ *" "str" ", size_t\ " "len" ");"
.HP \w'Ds\ *ds_set('u
.BI "Ds *ds_set(Ds\ *" "ds" ", char\ *" "str" ");"
.HP \w'Ds\ *ds_setn('u
.BI "Ds *ds_setn(Ds\ *" "ds" ", unsigned\ char\ *" "s" ", size_t\ " "slen" ");"
.HP \w'Ds\ *ds_range('u
.BI "Ds *ds_range(Ds\ *" "ds" ", char\ *" "str" ", char\ *" "range_spec" ", Range_syntax\ *" "ors" ");"
.HP \w'int\ ds_getc('u
.BI "int ds_getc(Ds\ *" "ds" ", FILE\ *" "fp" ", int\ *" "ch_ptr" ");"
.HP \w'Dsio\ *dsio_set('u
.BI "Dsio *dsio_set(Ds\ *" "ds" ", FILE\ *" "fp" ", char\ *" "buf" ", unsigned\ long\ " "len" ", int\ " "have_length" ");"
.HP \w'int\ dsio_free('u
.BI "int dsio_free(Ds\ *" "ds" ");"
.HP \w'int\ dsio_eof('u
.BI "int dsio_eof(Ds\ *" "ds" ");"
.HP \w'int\ dsio_nextc('u
.BI "int dsio_nextc(Ds\ *" "ds" ", int\ *" "ch_ptr" ");"
.HP \w'int\ dsio_peekc('u
.BI "int dsio_peekc(Ds\ *" "ds" ", int\ *" "ch_ptr" ");"
.HP \w'char\ *dsio_agets('u
.BI "char *dsio_agets(Ds\ *" "ds" ");"
.HP \w'char\ *dsio_gets('u
.BI "char *dsio_gets(Ds\ *" "ds" ");"
.HP \w'int\ dsio_load('u
.BI "int dsio_load(Ds\ *" "ds" ");"
.HP \w'char\ *dsio_load_str('u
.BI "char *dsio_load_str(Ds\ *" "ds" ");"
.HP \w'char\ *ds_gets('u
.BI "char *ds_gets(Ds\ *" "ds" ", FILE\ *" "fp" ");"
.HP \w'char\ *ds_agets('u
.BI "char *ds_agets(Ds\ *" "ds" ", FILE\ *" "fp" ");"
.HP \w'char\ *ds_agets_buf('u
.BI "char *ds_agets_buf(Ds\ *" "ds" ", char\ *" "buf" ");"
.HP \w'char\ *ds_prompt('u
.BI "char *ds_prompt(Ds\ *" "ds" ", char\ *" "prompt" ", unsigned\ int\ " "flag" ");"
.HP \w'char\ *ds_readline('u
.BI "char *ds_readline(Ds\ *" "ds" ", char\ *" "prompt" ", char\ *" "cprompt" ");"
.HP \w'Ds\ *ds_load_file('u
.BI "Ds *ds_load_file(Ds\ *" "ds" ", char\ *" "pathname" ");"
.HP \w'Ds\ *ds_agetf('u
.BI "Ds *ds_agetf(Ds\ *" "ds" ", FILE\ *" "fp" ");"
.HP \w'Ds\ *ds_getf('u
.BI "Ds *ds_getf(FILE\ *" "fp" ");"
.HP \w'int\ ds_sprintf('u
.BI "int ds_sprintf(Ds\ *" "ds" ", unsigned\ int\ " "offset" ", char\ *" "fmt" ", ...);"
.HP \w'int\ ds_asprintf('u
.BI "int ds_asprintf(Ds\ *" "ds" ", char\ *" "fmt" ", ...);"
.HP \w'int\ ds_vasprintf('u
.BI "int ds_vasprintf(Ds\ *" "ds" ", char\ *" "fmt" ", va_list\ " "ap" ");"
.HP \w'char\ *ds_xprintf('u
.BI "char *ds_xprintf(char\ *" "fmt" ", ...);"
.HP \w'char\ *ds_vxprintf('u
.BI "char *ds_vxprintf(char\ *" "fmt" ", va_list\ " "ap" ");"
.HP \w'FILE\ *ds_fopen_secure('u
.BI "FILE *ds_fopen_secure(const\ char\ *" "path" ", const\ char\ *" "mode" ", size_t\ " "size" ");"
.HP \w'int\ ds_fclose('u
.BI "int ds_fclose(FILE\ *" "fp" ");"
.HP \w'int\ ds_fclean('u
.BI "int ds_fclean(FILE\ *" "fp" ");"
.HP \w'Dsvec\ *dsvec_init('u
.BI "Dsvec *dsvec_init(Dsvec\ *" "dsv" ", size_t\ " "size" ");"
.HP \w'Dsvec\ *dsvec_alloc('u
.BI "Dsvec *dsvec_alloc(size_t\ " "size" ");"
.HP \w'Dsvec\ *dsvec_init_size('u
.BI "Dsvec *dsvec_init_size(Dsvec\ *" "dsv" ", size_t\ " "size" ", int\ " "n" ");"
.HP \w'Dsvec\ *dsvec_alloc_size('u
.BI "Dsvec *dsvec_alloc_size(size_t\ " "size" ", int\ " "n" ");"
.HP \w'void\ dsvec_free('u
.BI "void dsvec_free(Dsvec\ *" "dsv" ");"
.HP \w'Dsvec\ *dsvec_grow('u
.BI "Dsvec *dsvec_grow(Dsvec\ *" "dsv" ", unsigned\ int\ " "new_nelements" ");"
.HP \w'Dsvec\ *dsvec_subset('u
.BI "Dsvec *dsvec_subset(Dsvec\ *" "dsv" ", Dsvec\ *" "old_dsv" ", unsigned\ int\ " "start" ", int\ " "len" ");"
.HP \w'Dsvec\ *dsvec_copy('u
.BI "Dsvec *dsvec_copy(Dsvec\ *" "dsv" ", Dsvec\ *" "old_dsv" ");"
.HP \w'void\ *dsvec_ptr_index('u
.BI "void *dsvec_ptr_index(Dsvec\ *" "dsv" ", unsigned\ int\ " "ind" ");"
.HP \w'int\ dsvec_delete_ptr_index('u
.BI "int dsvec_delete_ptr_index(Dsvec\ *" "dsv" ", unsigned\ int\ " "ind" ");"
.HP \w'int\ dsvec_delete_ptr('u
.BI "int dsvec_delete_ptr(Dsvec\ *" "dsv" ", void\ *" "ptr" ");"
.HP \w'int\ dsvec_replace_ptr('u
.BI "int dsvec_replace_ptr(Dsvec\ *" "dsv" ", void\ *" "ptr" ", unsigned\ int\ " "ind" ");"
.HP \w'int\ dsvec_streq('u
.BI "int dsvec_streq(Dsvec\ *" "dsv1" ", Dsvec\ *" "dsv2" ");"
.HP \w'int\ dsvec_strneq('u
.BI "int dsvec_strneq(Dsvec\ *" "dsv1" ", Dsvec\ *" "dsv2" ", size_t\ " "len" ");"
.HP \w'int\ dsvec_rotate('u
.BI "int dsvec_rotate(Dsvec\ *" "dsv" ", int\ " "npos" ");"
.HP \w'Dsvec\ *dsvec_strlist('u
.BI "Dsvec *dsvec_strlist(Dsvec\ *" "dsv" ", char\ *" "str_spec" ");"
.HP \w'Dsvec\ *dsvec_slice('u
.BI "Dsvec *dsvec_slice(Dsvec\ *" "dsv" ", Dsvec\ *" "primary" ", unsigned\ int\ " "ind" ", unsigned\ int\ " "len" ");"
.HP \w'Dsvec\ *dsvec_range('u
.BI "Dsvec *dsvec_range(Dsvec\ *" "dsv" ", Dsvec\ *" "primary" ", char\ *" "range_spec" ", Range_syntax\ *" "ors" ");"
.HP \w'int\ dsvec_replace('u
.BI "int dsvec_replace(Dsvec\ *" "primary" ", unsigned\ int\ " "ind" ", unsigned\ int\ " "delete_len" ", Dsvec\ *" "secondary" ");"
.HP \w'int\ dsvec_append('u
.BI "int dsvec_append(Dsvec\ *" "primary" ", Dsvec\ *" "secondary" ");"
.HP \w'int\ dsvec_insert_ptr('u
.BI "int dsvec_insert_ptr(Dsvec\ *" "dsv" ", unsigned\ int\ " "ind" ", void\ *" "ptr" ");"
.HP \w'int\ dsvec_add_ptr('u
.BI "int dsvec_add_ptr(Dsvec\ *" "dsv" ", void\ *" "ptr" ");"
.HP \w'int\ dsvec_insert('u
.BI "int dsvec_insert(Dsvec\ *" "primary" ", unsigned\ int\ " "ind" ", Dsvec\ *" "secondary" ");"
.HP \w'int\ dsvec_delete('u
.BI "int dsvec_delete(Dsvec\ *" "dsv" ", unsigned\ int\ " "ind" ", unsigned\ int\ " "ndelete" ");"
.HP \w'int\ dsvec_add_obj('u
.BI "int dsvec_add_obj(Dsvec\ *" "dsv" ");"
.HP \w'void\ dsvec_sort('u
.BI "void dsvec_sort(Dsvec\ *" "dsv" ", int\ " "(*compar)(const\ void\ *,\ const\ void\ *)" ");"
.HP \w'Dsvec\ *dsvec_load('u
.BI "Dsvec *dsvec_load(Ds\ *" "ds" ", Dsvec\ *" "dsv" ");"
.HP \w'Dsvec\ *ds_mkargv_add('u
.BI "Dsvec *ds_mkargv_add(Dsvec\ *" "dsv" ", char\ *" "el" ");"
.HP \w'Dsvec\ *ds_mkargv_addv('u
.BI "Dsvec *ds_mkargv_addv(Dsvec\ *" "dsv" ", int\ " "argc" ", char\ **" "argv" ");"
.sp
.nf
typedef struct Mkargv {
  int \fIkeepq\fR;
  int \fIkeepws\fR;
  char *\fIifs\fR;
  char *\fIstartq\fR;
  char *\fIendq\fR;
} Mkargv;
.fi
.HP \w'Dsvec\ *ds_mkargv('u
.BI "Dsvec *ds_mkargv(Dsvec\ *" "dsv" ", char\ *" "str" ", Mkargv\ *" "conf" ");"
.HP \w'char\ *ds_buf('u
.BI "char *ds_buf(Ds\ *" "ds" ");"
.HP \w'size_t\ ds_len('u
.BI "size_t ds_len(Ds\ *" "ds" ");"
.HP \w'size_t\ ds_size('u
.BI "size_t ds_size(Ds\ *" "ds" ");"
.HP \w'int\ ds_eq('u
.BI "int ds_eq(Ds\ *" "ds1" ", Ds\ *" "ds2" ");"
.HP \w'(TYPE)\ dsvec_ptr('u
.BI "(TYPE) dsvec_ptr(Ds\ *" "DSV" ", unsigned\ int\ " "IND" ", " "TYPE" ");"
.HP \w'(TYPE)\ dsvec_obj('u
.BI "(TYPE) dsvec_obj(Ds\ *" "DSV" ", unsigned\ int\ " "IND" ", " "TYPE" ");"
.HP \w'(TYPE)\ dsvec_new_obj('u
.BI "(TYPE) dsvec_new_obj(Ds\ *" "DSV" ", " "TYPE" ");"
.HP \w'(TYPE)\ dsvec_base_type('u
.BI "(TYPE) dsvec_base_type(Ds\ *" "DSV" ", " "TYPE" ");"
.HP \w'void\ **dsvec_base('u
.BI "void **dsvec_base(Dsvec\ *" "dsv" ");"
.HP \w'unsigned\ int\ dsvec_len('u
.BI "unsigned int dsvec_len(Dsvec\ *" "dsv" ");"
.sp
.nf
\fIextern int ds_default_clear_flag;\fR
\fIextern int ds_default_delnl_flag;\fR
\fIextern size_t ds_default_len_limit;\fR
\fIextern void *(*ds_default_malloc_func)(size_t size);\fR
\fIextern void *(*ds_default_free_func)(void *ptr);\fR

.fi
.SH "DESCRIPTION"
.PP
The
DS
library is a collection of functions for creating, manipulating, and formatting strings of bytes\&. The memory used by these strings is dynamically allocated and released as necessary\&. When used correctly, bugs caused by buffer overruns and other programming errors can be avoided\&. There are also functions for creating and manipulating dynamic vectors of pointers and objects\&.
.PP
\&...
.SS "Byte Strings"
.PP
A
\fBDs\fR
data structure represents a dynamic string\&. It must be initialized before it can be used\&. A
\fBDs\fR
variable contains several fields that may be set after initialization but before it is first used\&. Default values for some of these fields are copied from global variables exported by the library\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBInitialization\fR
.RS 4
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBManipulation\fR
.RS 4
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBFormatting\fR
.RS 4
.RE
.SS "Vectors"