form_cplx.h

Go to the documentation of this file.

/* Copyright (C) 2026 Chris Piker <chris-piker@uiowa.edu>
 *
 * Author: C. Piker, via Claude Opus 5
 *
 * This file is part of das2C, the Core Das2 C Library.
 *
 * Das2C is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * Das2C is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 2.1 along with das2C; if not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef _das_form_cplx_h_
#define _das_form_cplx_h_
 
#include <das3/form.h>
 
/* For the shared component-system numbering ONLY -- DAS_VSYS_UNKNOWN is the
   whole space's "no system" sentinel and form_vector.h is where the space is
   chartered.  This file learns nothing else about vectors from it: complex
   has no rule for one and declines the pairing.  form_geoloc.h reaches for the
   same header for the same reason. */
#include <das3/form_vector.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* --- component systems, the complex half --------------------------------- *
 *
 * The codes CONTINUE the numbering form_vector.h opens and form_geoloc.h
 * extends, for the reason stated there: one ubyte must read the same next to
 * whichever formalism handed it out.  A second space starting over at 1 would
 * make a bare system code meaningless without knowing its issuer, which is the
 * exact confusion the shared space exists to prevent.
 *
 * Sharing the space does NOT make these geometric.  das_vsys_str() and
 * das_geosys_str() answer NULL for both of them, which is correct: a complex
 * plane has no third component, no frame and no cross product, so no code in
 * this file may be handed to das_vsys_toCart().
 */
 
#define DAS_VSYS_RECT      0x00000007  /* real, imaginary       */
#define DAS_VSYS_POLAR     0x00000008  /* magnitude, phase      */
 
#define DAS_VSYS_CPLX_MIN  0x00000007
#define DAS_VSYS_CPLX_MAX  0x00000008
 
DAS_API const char* das_cplxsys_str(ubyte uSys);
 
DAS_API ubyte das_cplxsys_id(const char* sSys);
 
DAS_API const char* das_cplxsys_desc(ubyte uSys);
 
DAS_API const char* das_cplxsys_symbol(ubyte uSys, int iComp);
 
DAS_API bool das_cplx_toRect(ubyte uSys, const double* pIn, double* pOut);
 
DAS_API bool das_cplx_fromRect(ubyte uSys, const double* pIn, double* pOut);
 
/* Exported so that its address can be compared.  Client code uses the
   DAS_FORM_CPLX macro below and has no reason to name this directly. */
DAS_API extern const DasForm_VTbl das_form_cplx_vtbl;
 
#define DAS_FORM_CPLX (&das_form_cplx_vtbl)
 
DAS_API DasForm* new_DasFormCplx(ubyte uSysType);
 
DAS_API ubyte DasFormCplx_sysType(const DasForm* pThis);
 
/* To read a complex datum's two components use das_datum_toDoubles().  Values
   come back as stored, so a polar variable returns a magnitude and a phase in
   degrees.  Use das_cplx_toRect() above to convert them. */
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_form_cplx_h_ */