.\" cppawk: C preprocessor wrapper around awk
.\" Copyright 2022 Kaz Kylheku <kaz@kylheku.com>
.\"
.\" BSD-2 License
.\"
.\" 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 COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT HOLDER OR CONTRIBUTORS 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.
.de bk
.IP " "
.PP
..
.TH CPPAWK-FIELD 1 "19 April 2022" "cppawk Libraries" "Field Utilities"

.SH NAME
.I field
\- utilities for working with positional parameters ("fields")

.SH SYNOPSIS
.ft B
  #include <field.h>

  delf(\fIi\fP[, \fIn\fP])      \fI// delete n fields starting with i.\fP
  insf(\fIi\fP, ...)      \fI// insert one or more fields at position i.\fP
.ft R

.SH DESCRIPTION
.bk
The
.I <field.h>
header provides utilities for performing bulk operations on Awk positional
parameters, also referred to as fields.

.SS Function \fIdelf\fP
.bk
.B Syntax:

.ft B
  delf(\fIi\fP[ ,\fIn\fP])
.ft R

.B Description:

The
.B delf
function deletes
.I n
fields starting at field
.IR i .

If
.I i
exceeds
.B NF
or is less than
.BR 1 ,
or if
.I n
is less than 1, the function has no effect.

If
.I n
is omitted, it defaults to 1: one field is deleted.

If there are fields after the deleted fields, they are relocated so
that they start at position
.I i
and
.B NF
is adjusted accordingly.

If there are are only
.B n
or fewer fields starting at position
.BR i ,
then no fields have to be moved. In this case,
.B NF
is simply adjusted to the value of
.I i
.B "- 1"
to trim the fields away.

In all cases when
.B NF
is adjusted or fields are moved, the record
.B $0
is re-calculated in accordance with the Awk semantics for field manipulation.

.SS Macro \fIinsf\fP
.bk
.B Syntax:

.ft B
  insf(\fIi\fP, ...)
.ft R

.B Description:

The
.B insf
macro expands to a statement which inserts one or more fields at position
.IR i .
The number of fields inserted is determined by the number of variable
arguments after
.IR i ,
of which there must be between 1 and 32. These are the
.IR "field arguments" .

If
.I i
is less than 1, there is no effect. In that case, the argument expressions
which give the inserted field values are also not evaluated.

Let
.I n
be the number of field arguments being inserted.

The
.I i
argument may be greater than
.BR NF ,
in which case the specified fields are created, and
.B NF
is adjusted to include all of them in the position parameter array;
.B NF
will take on the value
.I i
.B +
.IR n .

If
.I i
is between 1 and
.BR NF ,
then the existing fields from
.I i
to
.B NF
move to higher positions to create a space for the inserted fields.
Field
.BI $ i
moves to
.BI $( i " + " n )
and so forth. Then the
.I n
field parameters are assigned into the positions
.BI $ i \fR,\fP
.BI $( i " + 1)" \fR,\fP
\fR...,\fP
.BI $( i " + " n " - 1)" \fR.\fP

In all cases when
.B NF
is adjusted and fields are assigned or moved, the record
.B $0
is re-calculated in accordance with the Awk semantics for field manipulation.

.SH SEE ALSO
cppawk(1), cppawk-cons(1)

.SH BUGS
The
.B insf
function is limited to 32 variadic arguments.

.SH AUTHOR
Kaz Kylheku <kaz@kylheku.com>

.SH COPYRIGHT
Copyright 2022, BSD2 License.