.\" gd_array_len.3.  The gd_array_len man page.
.\"
.\" Copyright (C) 2010, 2011, 2012, 2014 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_array_len 3 "27 May 2014" "Version 0.9.0" "GETDATA"
.SH NAME
gd_array_len \(em returns the length of a CARRAY or SARRAY field in a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "size_t gd_array_len(DIRFILE *" dirfile ", const char *" field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_array_len ()
function queries a dirfile(5) database specified by
.I dirfile
and returns the number of length of the
.BR CARRAY ", " CONST ", " STRING ,
or
.B SARRAY
field called
.IR field_code .
If
.I field_code
contains a valid representation suffix, it will be ignored.

The 
.I dirfile
argument must point to a valid DIRFILE object previously created by a call to
.BR gd_open (3).

.SH RETURN VALUE
Upon successful completion,
.BR gd_array_len ()
returns the array length of the field specified.  (The length of a
.B CONST
or a
.B STRING
field is always 1.)  On error, it returns zero and sets the dirfile error to a
non-zero error value.  Possible error values are:
.TP 8
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_CODE
The field specified by
.I field_code
was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_FIELD_TYPE
The field specified by
.I field_code
was not of one of the field types listed above.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).
.SH NOTES
This function used to be called
.BR gd_carray_len ().
This name can still be used, but it has been marked deprecated.
.SH SEE ALSO
.BR dirfile (5),
.BR gd_open (3),
.BR gd_error (3),
.BR gd_error_string (3)