/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Str.h
    Author:  Copyright  1992, 1993, 1994, 1995 Jason Williams, Jason Howat, 
                                                Julian Smith
    Version: 1.12 (17 May 1993)
    Purpose: Useful string functions not provided by ANSI, including functions
      	     to deal with CR-terminated strings, as used by the RISC OS Wimp.
      	     NB any control character will act as a terminator, not just 0 
      	     or CR.
    Mods:
             28 Sep 1995 JS Added strncpy0.
             17 Apr 1996 JS Removed duplicate declaration of stricmp.
             09 Dec 1996 JS Added Desk_Str_strdupcr().

*/

#ifndef __Desk_Str_h
#define __Desk_Str_h

#ifdef __cplusplus
	extern "C" {
#endif

/* We need size_t from stddef.h */
#include <stddef.h>


extern int Desk_strlencr(const char *s);
  /*  strlencr() == strlen()
   *  NOTE **** With release 2 of DeskLib this has been changed to return
   *  the length of the string EXCLUDING the terminator (i.e. it now returns
   *  1 less than it used to in Desklib 1)
   */

extern int Desk_strcmpcr(const char *s1, const char *s2);
  /*  strcmpcr() == strcmp)
   *  Returns 0 if the strings match
   *  Returns -1 if s1 < s2  (alphabetically less than, and/or shorter)
   *  Returns +1 if s1 > s2  (alphabetcally greater than, and/or longer)
   */


extern char *Desk_strcatcr(char *s1, const char *s2);
  /*  strcatcr() == strcat
   *  Concatenates s2 onto the end of s1. Returns s1.
   *  The returned string will be zero terminated.
   */


extern char *Desk_strcpycr(char *s1, const char *s2);
  /*  strcpycr() == strcpy
   *  Copies s2 into s1. Returns s1.
   *  The returned string will be zero terminated.
   */


extern char *Desk_strncpycr(char *s1, const char *s2, int n);
  /*  strncpycr() == strncpy
   *  Copies at most n chars of s2 into s1. Returns s1.
   *  NOTE that this will NOT terminate the string if s2 is longer than 'n'
   *  characters in length. If it is shorter, s1 will be zero-terminated.
   */


extern char *Desk_Str_LeafName(const char *path);
  /*  LeafName()
   *  Return a pointer to the leaf of 'FullPath'.
   *  Note that this pointer is within the 'FullPath' string.
   *  If no '.' is encountered in FullPath, then the pointer FullPath
   *  is returned
   */

#define Desk_LeafName Desk_Str_LeafName



extern int Desk_stricmp(const char *s1, const char *s2);
/*
Purpose:  As ANSI strcmp() function, but case insensitive.
*/


extern int Desk_strnicmp(const char *s1, const char *s2, size_t n);
/*
    Purpose:  As ANSI strncmp() function, but case insensitive.
*/


extern int Desk_stricmpcr(const char *s1, const char *s2);
/*
As stricmp() except works on CR-terminated strings.
*/

extern int Desk_strnicmpcr(const char *s1, const char *s2, size_t n);
/*
Purpose:  As strnicmp() function, but works on CR-terminated strings.
*/


extern char *Desk_strdup( const char *s);
/*
    Inputs:   s - the string to copy
    Returns:  Address of new string, or NULL if out of memory.
    Purpose:  Allocate memory for a copy of the string using Desk_DeskMem_XMalloc, 
              and copy the string into this memory.
*/


extern void Desk_Str_MakeCR(char *s, int Desk_max_len);
/*
    Inputs:   s - pointer to the string to change to a CR-terminated string.
      	      Desk_max_len - the number of characters to look for the null
      	      	      	terminator in before giving up (in which case it is
      	      	      	terminated at the Desk_max_len'th character).
    Purpose:  Converts a 0-terminated (ASCIIZ) string into a CR-terminated
      	      string.
    SeeAlso:  Desk_Str_MakeASCIIZ()
*/


extern void Desk_Str_MakeASCIIZ(char *s, int Desk_max_len);
/*
    void Desk_Str_MakeASCIIZ(char *s, int Desk_max_len);

    Inputs:   s - pointer to the string to change to a 0-terminated string.
      	      Desk_max_len - the number of characters to look for the null
      	      	      	terminator in before giving up (in which case it is
      	      	      	terminated at the Desk_max_len'th character).
    Purpose:  Converts a CR (or any other ctrl character)-terminated string
              into a 0-terminated (ASCIIZ) string.
    SeeAlso:  Desk_Str_MakeCR()
*/


extern char Desk_Str_MakeHex(int n);
/*
    char Desk_Str_MakeHex(int n);

    Inputs:   n - the digit to convert to hexadecimal (n should be in the
      	      	  range 0-15).
    Returns:  The character representing the digit; '0'..'9', 'A'..'Z'.
    Purpose:  Converts an integer in the range 0 to 15 to a character that
      	      represents it in hexadecimal.
      	      If n is outside the range, '?' is returned.
    SeeAlso:  Desk_Str_DecodeHex()
*/


extern int Desk_Str_DecodeHex(char digit);
/*
    int Desk_Str_DecodeHex(char digit);

    Inputs:   digit - character representing the hex digit to convert.
    Returns:  The integer value of 'digit', or -1 for error.
    Purpose:  Convert a hexadecimal digit of the form '0'..'9', 'A'..'Z'
      	      into an integer.
      	      If the character is not a legal hexadecimal digit, -1 is
      	      returned.
    SeeAlso:  HexDigit()
*/


extern char *Desk_Str_StrNCpy0( char *s1, const char *s2, int n);
/*
As strncpy, but sets s1[n]=0 .
 */

#define	Desk_strncpy0( s1, s2, n)	Desk_Str_StrNCpy0( s1, s2, n)


char*	Desk_Str_strdupcr( const char* s);
/*
Duplicates the specified ctrl-terminated string. Output string is 0
terminated.
 */


#ifdef __cplusplus
}
#endif

#endif
