/usr/share/doc/libstarlink-ast-doc/node219.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!--Converted with LaTeX2HTML 2008 (1.71)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>AST Memory Management and Utility Functions</TITLE>
<META NAME="description" CONTENT="AST Memory Management and Utility Functions">
<META NAME="keywords" CONTENT="sun211">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">

<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="sun211.css">

<LINK REL="next" HREF="node220.html">
<LINK REL="previous" HREF="node218.html">
<LINK REL="up" HREF="sun211.html">
<LINK REL="next" HREF="node220.html">
</HEAD>

<BODY >

<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html2728"
  HREF="node220.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html2726"
  HREF="sun211.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html2720"
  HREF="node218.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev.png"></A>   
<BR>
<B> Next:</B> <A NAME="tex2html2729"
  HREF="node220.html">FitsWcsCoverageFITS-WCS Coverage</A>
<B> Up:</B> <A NAME="tex2html2727"
  HREF="sun211.html">sun211</A>
<B> Previous:</B> <A NAME="tex2html2721"
  HREF="node218.html">UNIX Command Descriptions</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION000280000000000000000"></A><A NAME="ss:memoryfunctions"></A>
<BR>
AST Memory Management and Utility Functions
</H1>
AST provides a memory management layer that can be used in place of
system functions such as <TT>malloc</TT>, <TT>free</TT>, <TT>realloc</TT>,
<SPAN  CLASS="textit">etc.</SPAN> The AST replacements for these functions ( <TT>astMallocastMalloc</TT>,
<TT>astFreeastFree</TT> and <TT>astReallocastRealloc</TT>) add extra information to each
allocated memory block that allows AST to check the validity of supplied
pointers. For example, this extra information allows <TT>astFree</TT> to
detect if the supplied pointer has already been freed, and if so to issue
an appropriate error message. The existence of this extra information is
invisible to outside callers, and stored in a header block located just
before the returned memory block.

<P>
In addition to the standard functions, AST provides other memory management
functions, such as:

<P>
<DL>
<DT><STRONG><TT>astStoreastStore</TT></STRONG></DT>
<DD>- stores data in dynamically allocated memory, allocating
the memory (or adjusting the size of previously allocated memory) to match
the amount of data to be stored.
</DD>
<DT><STRONG><TT>astGrowastGrow</TT></STRONG></DT>
<DD>- allocates and expands memory to hold an adjustable-sized array.
</DD>
<DT><STRONG><TT>astAppendStringastAppendString</TT></STRONG></DT>
<DD>- allocates and expands memory to hold a
concatenated string.
</DD>
</DL>

<P>
Theses are just a few of the available utilities functions in the AST
memory management layer. Prototypes for all AST memory management
functions are included in the header file ``<TT>ast.h</TT>''.

<P>
An important restriction on these functions is that pointers created by
other memory management functions, such as the system version of <TT>malloc</TT> <SPAN  CLASS="textit">etc.</SPAN>, should never supplied to an AST memory management
function. Only pointers created by AST should be used by these functions.

<P>
In addition to memory management functions, AST provides various other
utility functions, such as a basic regular expression facility, and other
string manipulation functions. These are also documented in this appendix.

<P>
The AST memory management layer is implemented on top of the usual <TT>malloc</TT>, tt free and <TT>realloc</TT> functions. By default these will be
the standard functions provided by &lt;stdlib.h&gt;. However, the facilities of
the STARMEM package (included in the Starlink Software Collection) can be
used to specify alternative functions to use. This requires that AST be
configured using the ``-with-starmem'' option when it is built.

<P>
The STARMEM package provides a wrapper for the standard malloc
implementation that enables the user to switch malloc schemes at runtime
by setting the STARMEM_MALLOC environment variable. Currently allowed
values for this variable are:

<P>
<DL>
<DT><STRONG>SYSTEM</STRONG></DT>
<DD>- standard system malloc/free - the default
</DD>
<DT><STRONG>DL</STRONG></DT>
<DD>- Doug Lea's malloc/free
</DD>
<DT><STRONG>GC</STRONG></DT>
<DD>- Hans-Boehm Garbage Collection
</DD>
</DL>

<P>
<SMALL CLASS="SMALL">
   astAppendString

   Append a string to another string which grows dynamically

   
      This function appends one string to another dynamically
      allocated string, extending the dynamic string as necessary to
      accommodate the new characters (plus the final null).
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astAppendString( char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str1, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>nc, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str2 )
   
   
      
         str1
      
         Pointer to the null-terminated dynamic string, whose memory
         has been allocated using an AST memory allocation function.
         If no space has yet been allocated for this string, a NULL
         pointer may be given and fresh space will be allocated by this
         function.
      
      
         nc
      
         Pointer to an integer containing the number of characters in
         the dynamic string (excluding the final null). This is used
         to save repeated searching of this string to determine its
         length and it defines the point where the new string will be
         appended. Its value is updated by this function to include
         the extra characters appended.
</SMALL>
<P>
<SMALL CLASS="SMALL">If <TT>"</TT> str1<TT>"</TT>  is NULL, the initial value supplied for <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>nc<TT>"</TT>  will
         be ignored and zero will be used.
      
      
         str2
      
         Pointer to a constant null-terminated string, a copy of which
         is to be appended to <TT>"</TT> str1<TT>"</TT> .
      
   
   
      
         astAppendString()
      
         A possibly new pointer to the dynamic string with the new string
         appended (its location in memory may have to change if it has to
         be extended, in which case the original memory is automatically
         freed by this function). When the string is no longer required,
         its memory should be freed using astFreeastFree.
      
   
   
      
          If this function is invoked with the global error status set
         or if it should fail for any reason, then the returned pointer
         will be equal to <TT>"</TT> str1<TT>"</TT>  and the dynamic string contents will be
         unchanged.
      
   
</TT>

   astAppendStringf

   Append a string to another string, allowing printf format specifiers

   
      This function appends one string to another dynamically
      allocated string, extending the dynamic string as necessary to
      accommodate the new characters (plus the final null). It is the
      same as astAppendStringastAppendString, except that the <TT>"</TT> str2<TT>"</TT>  string ay include
      printf format specifiers.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astAppendStringf( char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str1, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>nc, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str2, ... )
   
   
      
         str1
      
         Pointer to the null-terminated dynamic string, whose memory
         has been allocated using an AST memory allocation function.
         If no space has yet been allocated for this string, a NULL
         pointer may be given and fresh space will be allocated by this
         function.
      
      
         nc
      
         Pointer to an integer containing the number of characters in
         the dynamic string (excluding the final null). This is used
         to save repeated searching of this string to determine its
         length and it defines the point where the new string will be
         appended. Its value is updated by this function to include
         the extra characters appended.
</SMALL>
<P>
<SMALL CLASS="SMALL">If <TT>"</TT> str1<TT>"</TT>  is NULL, the initial value supplied for <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>nc<TT>"</TT>  will
         be ignored and zero will be used.
      
      
         str2
      
         Pointer to a constant null-terminated string, a copy of which
         is to be appended to <TT>"</TT> str1<TT>"</TT> . It may contain format
         specifications such as used with the C <TT>"</TT> printf<TT>"</TT>  family of
         functions.
      
      
         ...
      
         Additional optional arguments (as used by e.g. <TT>"</TT> printf<TT>"</TT> )
         which specify values which are to be substituted into the <TT>"</TT> str2<TT>"</TT>
         string in place of any format specifications.
      
   
   
      
         astAppendString()
      
         A possibly new pointer to the dynamic string with the new string
         appended (its location in memory may have to change if it has to
         be extended, in which case the original memory is automatically
         freed by this function). When the string is no longer required,
         its memory should be freed using astFreeastFree.
      
   
   
      
          If this function is invoked with the global error status set
         or if it should fail for any reason, then the returned pointer
         will be equal to <TT>"</TT> str1<TT>"</TT>  and the dynamic string contents will be
         unchanged.
      
   
</TT>

   astCalloc

   Allocate and initialise memory

   
      This function allocates memory in a similar manner to the
      standard C <TT>"</TT> calloc<TT>"</TT>  function, but with improved security
      (against memory leaks, etc.) and with error reporting. It also
      fills the allocated memory with zeros.
</SMALL>
<P>
<SMALL CLASS="SMALL">Like astMallocastMalloc, it allows zero-sized memory allocation
      (without error), resulting in a NULL returned pointer value.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astCalloc( size_t nmemb, size_t size )
   
   
      
         nmemb
      
         The number of array elements for which memory is to be allocated.
      
      
         size
      
         The size of each array element, in bytes.
      
   
   
      
         astCalloc()
      
         If successful, the function returns a pointer to the start of
         the allocated memory region. If the size allocated is zero, this
         will be a NULL pointer.
      
   
   
      
          A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      
   
</TT>

   astChr2Double

   read a double value from a string

   
      This function reads a double from the supplied null-terminated string,
      ignoring leading and trailing white space. AST__BAD is ereturned
      without error if the string is not a numerical value.
   
   Synopsis<TT>
      double astChr2Double( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str )
   
   
      
         str
      
         Pointer to the string.
      
   
   
      
         astChr2Double()
      
         The double value, or AST__BAD.
      
   
   
      
          A value of AST__BAD is returned if this function is invoked with
         the global error status set or if it should fail for any reason.
      
   
</TT>

   astChrCase

   Convert a string to upper or lower case

   
      This function converts a supplied string to upper or lower case,
      storing the result in a supplied buffer. The astStringCaseastStringCase function
      is similar, but stores the result in a dynamically allocated buffer.
   
   Synopsis<TT>
      void astChrCase( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>in, char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>out, int upper, int blen, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>status )
   
   
      
         in
      
         Pointer to the null terminated string to be converted. If this
         is NULL, the supplied contents of the <TT>"</TT> out<TT>"</TT>  string are used as
         the input string.
      
      
         out
      
         Pointer to the buffer to receive the converted string. The
         length of this buffer is given by <TT>"</TT> blen<TT>"</TT> . If NULL is supplied
         for <TT>"</TT> in<TT>"</TT> , then the supplied contents of <TT>"</TT> out<TT>"</TT>  are converted and
         written back into <TT>"</TT> out<TT>"</TT>  over-writing the supplied contents.
      
      
         upper
      
         If non-zero, the string is converted to upper case. Otherwise it
         is converted to lower case.
      
      
         blen
      
         The length of the output buffer. Ignored if <TT>"</TT> in<TT>"</TT>  is NULL. No
         more than <TT>"</TT> blen - 1<TT>"</TT>  characters will be copied from <TT>"</TT> in<TT>"</TT>  to
         <TT>"</TT> out<TT>"</TT> , and a terminating null character will then be added.
      
   
</TT>

   astChrLen

   Determine the used length of a string

   
      This function returns the used length of a string. This excludes any
      trailing white space or non-printable characters (such as the
      trailing null character).
   
   Synopsis<TT>
      size_t astChrLen( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>string )
   
   
      
         string
      
         Pointer to the string.
      
   
   
      
         astChrLen()
      
         The number of characters in the supplied string, not including the
         trailing newline, and any trailing white-spaces or non-printable
         characters.
      
   
</TT>

   astChrMatch

   Case insensitive string comparison

   
      This function compares two null terminated strings for equality,
      discounting differences in case and any trailing white space in either
      string.
   
   Synopsis<TT>
      int astChrMatch( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str1, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str2 )
   
   
      
         str1
      
         Pointer to the first string.
      
      
         str2
      
         Pointer to the second string.
      
   
   
      
         astChrMatch()
      
         Non-zero if the two strings match, otherwise zero.
      
   
   
      
          A value of zero is returned if this function is invoked with the
         global error status set or if it should fail for any reason.
      
   
</TT>

   astChrMatchN

   Case insensitive string comparison of at most N characters

   
      This function compares two null terminated strings for equality,
      discounting differences in case and any trailing white space in either
      string. No more than <TT>"</TT> n<TT>"</TT>  characters are compared.
   
   Synopsis<TT>
      int astChrMatchN( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str1, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str2, size_t n )
   
   
      
         str1
      
         Pointer to the first string.
      
      
         str2
      
         Pointer to the second string.
      
      
         n
      
         Maximum number of characters to compare.
      
   
   
      
         astChrMatchN()
      
         Non-zero if the two strings match, otherwise zero.
      
   
   
      
          A value of zero is returned if this function is invoked with the
         global error status set or if it should fail for any reason.
      
   
</TT>

   astChrSplit

   Extract words from a supplied string

   
      This function extracts all space-separated words form the supplied
      string and returns them in an array of dynamically allocated strings.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astChrSplit_( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n )
   
   
      
         str
      
         Pointer to the string to be split.
      
      
         n
      
         Address of an int in which to return the number of words returned.
      
   
   
      
         astChrSplit()
      
         A pointer to a dynamically allocated array containing <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n<TT>"</TT>  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a word extracted from the supplied string. Each
         of these words will have no leading or trailing white space.
      
   
   
      
          A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      
   
</TT>

   astChrSplitC

   Split a string using a specified character delimiter

   
      This function extracts all sub-strings separated by a given
      character from the supplied string and returns them in an array
      of dynamically allocated strings. The delimiter character itself
      is not included in the returned strings.
</SMALL>
<P>
<SMALL CLASS="SMALL">Delimiter characters that are preceded by <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN><TT>"</TT>  are not used as
      delimiters but are included in the returned word instead (without
      the <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN><TT>"</TT> ).
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astChrSplitC( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str, char c, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n )
   
   
      
         str
      
         Pointer to the string to be split.
      
      
         c
      
         The delimiter character.
      
      
         n
      
         Address of an int in which to return the number of words returned.
      
   
   
      
         astChrSplitC()
      
         A pointer to a dynamically allocated array containing <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n<TT>"</TT>  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a word extracted from the supplied string.
      
   
   
      
          A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      
   
</TT>

   astChrSplitRE

   Extract sub-strings matching a specified regular expression

   
      This function compares the supplied string with the supplied
      regular expression. If they match, each section of the test string
      that corresponds to a parenthesised sub-string in the regular
      expression is copied and stored in the returned array.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astChrSplitRE( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>str, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>regexp, int <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n,
                            const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>matchend )
   
   
      
         str
      
         Pointer to the string to be split.
      
      
         regexp
      
         The regular expression. See <TT>"</TT> Template Syntax:<TT>"</TT>  in the astChrSubastChrSub
         prologue. Note, this function differs from astChrSub in that any
         equals signs (=) in the regular expression are treated literally.
      
      
         n
      
         Address of an int in which to return the number of sub-strings
         returned.
      
      
         matchend
      
         A pointer to a location at which to return a pointer to the
         character that follows the last character within the supplied test
         string that matched any parenthesises sub-section of <TT>"</TT> regexp<TT>"</TT> . A
         NULL pointer is returned if no matches were found. A NULL pointer
         may be supplied if the location of the last matching character is
         not needed.
      
   
   
      
         astChrSplitRE()
      
         A pointer to a dynamically allocated array containing <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>n<TT>"</TT>  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a sub-string extracted from the supplied string.
         The array itself, and the strings within it, should all be freed
         using astFreeastFree when no longer needed.
      
   
   
      
          If a parenthesised sub-string in the regular expression is matched
         by more than one sub-string within the test string, then only the
         first is returned. To return multiple matches, the regular
         expression should include multiple copies of the parenthesised
         sub-string (for instance, separated by <TT>"</TT> .<SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
 SRC="img243.png"
 ALT="$+$"></SPAN>?<TT>"</TT>  if the intervening
         string is immaterial).
</SMALL>
<P>
<SMALL CLASS="SMALL">
          A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      
   
</TT>

   astChrSub

   Performs substitutions on a supplied string

   
      This function checks a supplied test string to see if it matches a
      supplied template. If it does, specified sub-sections of the test
      string may optionally be replaced by supplied substitution strings.
      The resulting string is returned.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astChrSub( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>test, const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>pattern,
                       const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>subs[], int nsub )
   
   
      
         test
      
         The string to be tested.
      
      
         pattern
      
         The template string. See <TT>"</TT> Template Syntax:<TT>"</TT>  below.
      
      
         subs
      
         An array of strings that are to replace the sections of the test
         string that match each parenthesised sub-string in <TT>"</TT> pattern<TT>"</TT> . The
         first element of <TT>"</TT> subs<TT>"</TT>  replaces the part of the test string that
         matches the first parenthesised sub-string in the template, etc.
</SMALL>
<P>
<SMALL CLASS="SMALL">If <TT>"</TT> nsub<TT>"</TT>  is zero, then the <TT>"</TT> subs<TT>"</TT>  pointer is ignored. In this
         case, substitution strings may be specified by appended them to
         the end of the <TT>"</TT> pattern<TT>"</TT>  string, separated by <TT>"</TT> =<TT>"</TT>  characters.
         Note, if you need to include a literal <TT>"</TT> =<TT>"</TT>  character in the
         pattern, precede it by an escape <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN><TT>"</TT>  character.
      
      
         nsub
      
         The number of substitution strings supplied in array <TT>"</TT> subs<TT>"</TT> .
      
   
   
      
         astChrSub()
      
         A pointer to a dynamically allocated string holding the result
         of the substitutions, or NULL if the test string does not match
         the template string. This string should be freed using astFreeastFree
         when no longer needed. If no substituions are specified then a
         copy of the test string is returned if it matches the template.
      
   
   
      
          A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied test string does not match the template.
      
   
   
      Template Syntax
   
      The template syntax is a minimal form of regular expression, The
      quantifiers allowed are <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><TT>"</TT> , <TT>"</TT> ?<TT>"</TT> , <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
 SRC="img243.png"
 ALT="$+$"></SPAN><TT>"</TT> , <TT>"</TT> {n}<TT>"</TT> , <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>?<TT>"</TT>  and <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="33" ALIGN="MIDDLE" BORDER="0"
 SRC="img243.png"
 ALT="$+$"></SPAN>?<TT>"</TT>  (the
      last two are non-greedy - they match the minimum length possible
      that still gives an overall match to the template). The only
      constraints allowed are <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="15" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img307.png"
 ALT="$\wedge$"></SPAN><TT>"</TT>  and <TT>"</TT> $<TT>"</TT> . The following atoms are allowed:
</SMALL>
<P>
<SMALL CLASS="SMALL">
          [chars]: Matches any of the specified characters.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          [<SPAN CLASS="MATH"><IMG
 WIDTH="15" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img307.png"
 ALT="$\wedge$"></SPAN>chars]: Matches anything but the specified characters.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          .: Matches any single character.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          x: Matches the character x so long as x has no other significance.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>x: Always matches the character x (except for [dDsSwW]).
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>d: Matches a single digit.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>D: Matches anything but a single digit.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>w: Matches any alphanumeric character, and <TT>"</TT> _<TT>"</TT> .
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>W: Matches anything but alphanumeric characters, and <TT>"</TT> _<TT>"</TT> .
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>s: Matches white space.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img305.png"
 ALT="$\backslash$"></SPAN>S: Matches anything but white space.
</SMALL>
<P>
<SMALL CLASS="SMALL">
      Note, minus signs (<TT>"</TT> -<TT>"</TT> ) within brackets have no special significance,
      so ranges of characters must be specified explicitly.
</SMALL>
<P>
<SMALL CLASS="SMALL">Multiple template strings can be concatenated, using the <TT>"</TT> <SPAN CLASS="MATH"><IMG
 WIDTH="10" HEIGHT="37" ALIGN="MIDDLE" BORDER="0"
 SRC="img306.png"
 ALT="$\vert$"></SPAN><TT>"</TT>
      character to separate them. The test string is compared against
      each one in turn until a match is found.
</SMALL>
<P>
<SMALL CLASS="SMALL">Parentheses are used within each template to identify sub-strings
      that are to be replaced by the strings supplied in <TT>"</TT> sub<TT>"</TT> .
</SMALL>
<P>
<SMALL CLASS="SMALL">If <TT>"</TT> nsub<TT>"</TT>  is supplied as zero, then substitution strings may be
      specified by appended them to the end of the <TT>"</TT> pattern<TT>"</TT>  string,
      separated by <TT>"</TT> =<TT>"</TT>  characters. If <TT>"</TT> nsub<TT>"</TT>  is not zero, then any
      substitution strings appended to the end of <TT>"</TT> pattern<TT>"</TT>  are ignored.
</SMALL>
<P>
<SMALL CLASS="SMALL">Each element of <TT>"</TT> subs<TT>"</TT>
      may contain a reference to a token of the
      form <TT>"</TT> $1<TT>"</TT> , <TT>"</TT> $2<TT>"</TT> , etc. The <TT>"</TT> $1<TT>"</TT>  token will be replaced by the part
      of the test string that matched the first parenthesised sub-string
      in <TT>"</TT> pattern<TT>"</TT> . The <TT>"</TT> $2<TT>"</TT>  token will be replaced by the part of the
      test string that matched the second parenthesised sub-string in
      <TT>"</TT> pattern<TT>"</TT> , etc.
   
</TT>

   astChrTrunc

   Terminate a string to exclude trailing spaces

   
      This function pokes a null character into the supplied string to
      remove any trailing spaces.
   
   Synopsis<TT>
      void astChrTrunc( char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>text )
   
   
      
         text
      
         The string to be truncated.
      
   
</TT>

   astFree

   Free previously allocated memory

   
      This function frees memory that has previouly been dynamically
      allocated using one of the AST memory function.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astFree( void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr )
   
   
      
         ptr
      
         Pointer to previously allocated memory. An error will result
         if the memory has not previously been allocated by another
         function in this module. However, a NULL pointer value is
         accepted (without error) as indicating that no memory has yet
         been allocated, so that no action is required.
      
   
   
      
         astFree()
      
         Always returns a NULL pointer.
      
   
</TT>

   astFreeDouble

   Free previously double allocated memory

   
      This function frees memory that has previouly been dynamically
      allocated using one of the AST memory function. It assumes that
      the supplied pointer is a pointer to an array of pointers. Each
      of these pointers is first freed, and then the supplied pointer
      is freed.
</SMALL>
<P>
<SMALL CLASS="SMALL">Note, this routine should not be used with arrays allocated
      by astGrowastGrow since astGrow over-allocates and so there may be
      non-initialised pointers at the end of the array.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astFreeDouble( void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr )
   
   
      
         ptr
      
         Pointer to previously allocated memory. An error will result
         if the memory has not previously been allocated by another
         function in this module. However, a NULL pointer value is
         accepted (without error) as indicating that no memory has yet
         been allocated, so that no action is required.
      
   
   
      
         astFreeDouble()
      
         Always returns a NULL pointer.
      
   
</TT>

   astGrow

   Allocate memory for an adjustable array

   
      This function allocates memory in which to store an array of
      data whose eventual size is unknown. It should be invoked
      whenever a new array size is determined and will appropriately
      increase the amount of memory allocated when necessary. In
      general, it will over-allocate in anticipation of future growth
      so that the amount of memory does not need adjusting on every
      invocation.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astGrow( void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr, int n, size_t size )
   
   
      
         ptr
      
         Pointer to previously allocated memory (or NULL if none has
         yet been allocated).
      
      
         n
      
         Number of array elements to be stored (may be zero).
      
      
         size
      
         The size of each array element.
      
   
   
      
         astGrow()
      
         If the memory was allocated successfully, a pointer to the start
         of the possibly new memory region is returned (this may be the
         same as the original pointer).
      
   
   
      
          When new memory is allocated, the existing contents are preserved.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          This function does not free memory once it is allocated, so
         the size allocated grows to accommodate the maximum size of the
         array (or <TT>"</TT> high water mark<TT>"</TT> ). Other memory handling routines may
         be used to free the memory (or alter its size) if necessary.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          If this function is invoked with the global error status set,
         or if it fails for any reason, the original pointer value is
         returned and the memory contents are unchanged.
      
   
</TT>

   astIsDynamic

   Returns a flag indicating if memory was allocated dynamically

   
      This function takes a pointer to a region of memory and tests if
      the memory has previously been dynamically allocated using other
      functions from this module. It does this by checking for the
      presence of a <TT>"</TT> magic<TT>"</TT>  number in the header which precedes the
      allocated memory. If the magic number is not present (or the
      pointer is invalid for any other reason), zero is returned.
      Otherwise 1 is returned.
   
   Synopsis<TT>
      int astIsDynamic_( const void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr )
   
   
      
         ptr
      
         Pointer to test.
      
   
   
      
         astIsDynamic()
      
         Non-zero if the memory was allocated dynamically. Zero is returned
         if the supplied pointer is NULL.
      
   
   
      
          A value of zero is returned if this function is invoked with
         the global error status set, or if it fails for any reason.
      
   
</TT>

   astMalloc

   Allocate memory

   
      This function allocates memory in a similar manner to the
      standard C <TT>"</TT> malloc<TT>"</TT>  function, but with improved security
      (against memory leaks, etc.) and with error reporting. It also
      allows zero-sized memory allocation (without error), resulting
      in a NULL returned pointer value.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astMalloc( size_t size )
   
   
      
         size
      
         The size of the memory region required (may be zero).
      
   
   
      
         astMalloc()
      
         If successful, the function returns a pointer to the start of
         the allocated memory region. If the size allocated is zero, this
         will be a NULL pointer.
      
   
   
      
          A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      
   
</TT>

   astMemCaching

   Controls whether allocated but unused memory is cached in this module

   
      This function sets a flag indicating if allocated but unused memory
      should be cached or not. It also returns the original value of the
      flag.
</SMALL>
<P>
<SMALL CLASS="SMALL">If caching is switched on or off as a result of this call, then the
      current contents of the cache are discarded.
</SMALL>
<P>
<SMALL CLASS="SMALL">Note, each thread has a separate cache. Calling this function
      affects only the currently executing thread.
   
   Synopsis<TT>
      int astMemCaching( int newval )
   
   
      
         newval
      
         The new value for the MemoryCaching tuning parameter (see
         astTuneastTune in objectc.c). If AST__TUNULL is supplied, the current
         value is left unchanged.
      
   
   
      
         astMemCaching()
      
         The original value of the MemoryCaching tuning parameter.
      
   
</TT>

   astRealloc

   Change the size of a dynamically allocated region of memory

   
      This function changes the size of a dynamically allocated region
      of memory, preserving its contents up to the minimum of the old
      and new sizes. This may involve copying the contents to a new
      location, so a new pointer is returned (and the old memory freed
      if necessary).
</SMALL>
<P>
<SMALL CLASS="SMALL">This function is similar to the standard C <TT>"</TT> realloc<TT>"</TT>  function
      except that it provides better security against programming
      errors and also supports the allocation of zero-size memory
      regions (indicated by a NULL pointer).
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astRealloc( void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr, size_t size )
   
   
      
         ptr
      
         Pointer to previously allocated memory (or NULL if the
         previous size of the allocated memory was zero).
      
      
         size
      
         New size required for the memory region. This may be zero, in
         which case a NULL pointer is returned (no error results). It
         should not be negative.
      
   
   
      
         astRealloc()
      
         If the memory was reallocated successfully, a pointer to the
         start of the new memory region is returned (this may be the same
         as the original pointer). If size was given as zero, a NULL
         pointer is returned.
      
   
   
      
          If this function is invoked with the error status set, or if
         it fails for any reason, the original pointer value is returned
         and the memory contents are unchanged. Note that this behaviour
         differs from that of the standard C <TT>"</TT> realloc<TT>"</TT>  function which
         returns NULL if it fails.
      
   
</TT>

   astRemoveLeadingBlanks

   Remove any leading white space from a string

   
      This function moves characters in the supplied string to the left
      in order to remove any leading white space.
   
   Synopsis<TT>
      void astRemoveLeadingBlanks( char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>string )
   
   
      
         string
      
         Pointer to the string.
      
   
</TT>

   astSizeOf

   Determine the size of a dynamically allocated region of memory

   
      This function returns the size of a region of dynamically
      allocated memory.
   
   Synopsis<TT>
      size_t astSizeOf( const void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr )
   
   
      
         ptr
      
         Pointer to dynamically allocated memory (or NULL if the size
         of the allocated memory was zero).
      
   
   
      
         astSizeOf()
      
         The allocated size. This will be zero if a NULL pointer was
         supplied (no error will result).
      
   
   
      
          A value of zero is returned if this function is invoked with
         the global error status set, or if it fails for any reason.
      
   
</TT>

   astStore

   Store data in dynamically allocated memory

   
      This function stores data in dynamically allocated memory,
      allocating the memory (or adjusting the size of previously
      allocated memory) to match the amount of data to be stored.
   
   Synopsis<TT>
      void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astStore( void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>ptr, const void <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>data, size_t size )
   
   
      
         ptr
      
         Pointer to previously allocated memory (or NULL if none has
         yet been allocated).
      
      
         data
      
         Pointer to the start of the data to be stored. This may be
         given as NULL if there are no data, in which case it will be
         ignored and this function behaves like astReallocastRealloc, preserving
         the existing memory contents.
      
      
         size
      
         The total size of the data to be stored and/or the size of
         memory to be allocated. This may be zero, in which case the
         data parameter is ignored, any previously-allocated memory is
         freed and a NULL pointer is returned.
      
   
   
      
         astStore()
      
         If the data were stored successfully, a pointer to the start of
         the possibly new memory region is returned (this may be the same
         as the original pointer). If size was given as zero, a NULL
         pointer is returned.
      
   
   
      
          This is a convenience function for use when storing data of
         arbitrary size in memory which is to be allocated
         dynamically. It is appropriate when the size of the data will
         not change frequently because the size of the memory region will
         be adjusted to fit the data on every invocation.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          If this function is invoked with the error status set, or if
         it fails for any reason, the original pointer value is returned
         and the memory contents are unchanged.
      
   
</TT>

   astString

   Create a C string from an array of characters

   
      This function allocates memory to hold a C string and fills the
      string with the sequence of characters supplied. It then
      terminates the string with a null character and returns a
      pointer to its start. The memory used for the string may later
      be de-allocated using astFreeastFree.
</SMALL>
<P>
<SMALL CLASS="SMALL">This function is intended for constructing null terminated C
      strings from arrays of characters which are not null terminated,
      such as when importing a character argument from a Fortran 77
      program.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astString( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>chars, int nchars )
   
   
      
         chars
      
         Pointer to the array of characters to be used to fill the string.
      
      
         nchars
      
         The number of characters in the array (zero or more).
      
   
   
      
         astString()
      
         If successful, the function returns a pointer to the start of
         the allocated string. If the number of characters is zero, a
         zero-length string is still allocated and a pointer to it is
         returned.
      
   
   
      
          A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      
   
</TT>

   astStringArray

   Create an array of C strings from an array of characters

   
      This function turns an array of fixed-length character data into
      a dynamicllay allocated array of null-terminated C strings with
      an index array that may be used to access them.
</SMALL>
<P>
<SMALL CLASS="SMALL">The array of character data supplied is assumed to hold <TT>"</TT> nel<TT>"</TT>
      adjacent fixed-length strings (without terminating nulls), each
      of length <TT>"</TT> len<TT>"</TT>  characters. This function allocates memory and
      creates a null-terminated copy of each of these strings. It also
      creates an array of <TT>"</TT> nel<TT>"</TT>  pointers which point at the start of
      each of these new strings. A pointer to this index array is
      returned.
</SMALL>
<P>
<SMALL CLASS="SMALL">The memory used is allocated in a single block and should later
      be de-allocated using astFreeastFree.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN><SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astStringArray( const char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>chars, int nel, int len )
   
   
      
         chars
      
         Pointer to the array of input characters. The number of characters
         in this array should be at least equal to (nel <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN> len).
      
      
         nel
      
         The number of fixed-length strings in the input character
         array. This may be zero but should not be negative.
      
      
         len
      
         The number of characters in each fixed-length input
         string. This may be zero but should not be negative.
      
   
   
      
         astStringArray()
      
         A pointer to the start of the index array, which contains <TT>"</TT> nel<TT>"</TT>
         pointers pointing at the start of each null-terminated output
         string.
</SMALL>
<P>
<SMALL CLASS="SMALL">The returned pointer should be passed to astFree to de-allocate
         the memory used when it is no longer required. This will free
         both the index array and the memory used by the strings it
         points at.
      
   
   
      
          A NULL pointer will also be returned if the value of <TT>"</TT> nel<TT>"</TT>  is
         zero, in which case no memory is allocated.
</SMALL>
<P>
<SMALL CLASS="SMALL">
          A pointer value of NULL will also be returned if this function
         is invoked with the global error status set or if it fails for
         any reason.
      
   
</TT>

   astStringCase

   Convert a string to upper or lower case

   
      This function converts a supplied string to upper or lower case,
      storing the result in dynamically allocated memory. The astChrCaseastChrCase
      function is similar, but stores the result in a supplied buffer.
   
   Synopsis<TT>
      char <SPAN CLASS="MATH"><IMG
 WIDTH="14" HEIGHT="19" ALIGN="BOTTOM" BORDER="0"
 SRC="img34.png"
 ALT="$*$"></SPAN>astStringCase( const char string, int upper )
   
   
      
         string
      
         Pointer to the null terminated string to be converted.
      
      
         upper
      
         If non-zero, the string is converted to upper case. Otherwise it
         is converted to lower case.
      
   
   
      
         astStringCase()
      
         If successful, the function returns a pointer to the start of
         the allocated string. The returned memory should be freed using
         astFreeastFree when no longer needed.
      
   
   
      
          A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      
   
</TT>
</SMALL>
<P>

<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html2728"
  HREF="node220.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="/usr/share/latex2html/icons/next.png"></A> 
<A NAME="tex2html2726"
  HREF="sun211.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up.png"></A> 
<A NAME="tex2html2720"
  HREF="node218.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev.png"></A>   
<BR>
<B> Next:</B> <A NAME="tex2html2729"
  HREF="node220.html">FitsWcsCoverageFITS-WCS Coverage</A>
<B> Up:</B> <A NAME="tex2html2727"
  HREF="sun211.html">sun211</A>
<B> Previous:</B> <A NAME="tex2html2721"
  HREF="node218.html">UNIX Command Descriptions</A></DIV>
<!--End of Navigation Panel-->

</BODY>
</HTML>
libstarlink-ast-doc 8.6.2+dfsg-2 / usr / share / doc / libstarlink-ast-doc / node219.html
