#ifndef _apl_tokenizers_stripapi_h_
#define _apl_tokenizers_stripapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: Utility functions for identifing tokens (STRIP)
**
** DESCRIPTION:
**  This file a colleciton of routines that can be used to identify
**  tokens seperated by whitespace and/or arbitrary character set.
**  
**  WHITESPACE:
**  -----------
**  By default the standard C library function isspace() is used
**  to determine whitespace characters.  The application can supply
**  its only definition of whitepsace by using the compile switch:
**  USE_APL_STRIP_CUSTOM_WHITESPACE and then implementing the
**  the function: AplBool Apl_cbIsSpace( int c );
**  
**  STRLEN:
**  -------
**  By default the standard C library function strlen() is used
**  is several of the routines.  If the application does not use
**  and/or have the standard C string functions (aka string.h) then 
**  define the compile switch: USE_APL_STRIP_NO_STRING_H and then
**  implement the function: AplSize_t Apl_cbStrlen( const char* s );
**  
**  
** CONFIGURATION 
** -------------
**  COMPILE:     USE_APL_STRIP_CUSTOM_WHITESPACE
**               USE_APL_STRIP_NO_STRING_H
**
**  APPLICATION: none.
**
**  PLATFORM:    none.
**
**
**  NOTES:
**  1. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as macros.
----------------------------------------------------------------------------*/

#include "apl/types/types.h"                    /* For: basic types */
#include "apl/parsing/tokenizers/strip.h"       /* For: implementation */


#ifdef __cplusplus
extern "C" {
#endif


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** This method returns a pointer to the FIRST non-whitespace character in the
    the specified null-terminated string.  NOTE: This method does NOT modify
    the original string in any way!

    Prototype:
        const char* Apl_stripSpaces(const char *s);
 */
#define Apl_stripSpaces                  _Apl_stripSpaces

/** This method returns a pointer to the FIRST whitespace character in the
    the specified null-terminated string.  NOTE: This method does NOT modify
    the original string in any way!

    This method is usefull in finding the 'next' token in a string, for example: 

        // Returns a pointer to the first token in 'input'
        const char* token = Apl_stripSpaces(input)

        // Returns a pointer to the second token in 'input'
        token = Apl_stripSpaces(Apl_stripNotSpaces(token))


    Prototype:
        const char* Apl_stripNotSpaces(const char *s);
 */
#define Apl_stripNotSpaces               _Apl_stripNotSpaces

/** This method returns a pointer to the LAST non-whitespace character in the
    the specified null-terminated string.  NOTE: This method does NOT modify
    the original string in any way!

    Prototype:
        const char* Apl_stripTrailingSpaces(const char *s);
 */
#define Apl_stripTrailingSpaces          _Apl_stripTrailingSpaces

/** This method TRUNCATES the specified null-terminated string by eliminating
    any trailing white space.

    Prototype:
        void Apl_removeTrailingSpaces( char* s );
 */
#define Apl_removeTrailingSpaces         _Apl_removeTrailingSpaces

/** This method is the same as Apl_stripSpaces(), except the specified character
    set is used to terminate the search instead of the standard isspace()
    characters.

    Prototype:
        const char* Apl_stripChars(const char *s, const char* charsSet );
 */
#define Apl_stripChars                  _Apl_stripChars

/** This method is the same as Apl_stripNotSpaces(), except the specified 
    character set is used to terminate the search instead of the standard 
    isspace() characters.

    Prototype:
        const char* Apl_stripNotChars( const char*s, const char* charsSet );
 */
#define Apl_stripNotChars               _Apl_stripNotChars

/** This method is the same as Apl_stripTrailingSpacess(), except the 
    specified character set is used to identify the last "non-whitespace" 
    character.
        
    Prototype:
        const char* Apl_stripTrailingChars(const char *s, const char* charsSet );
 */
#define Apl_stripTrailingChars          _Apl_stripTrailingChars

/** This method is the same as Apl_removeTrailingSpacess(), except the 
    specified characters set is used for "whitespace" any trailing 
    white space.

    Prototype:
        void Apl_removeTrailingChars( char* s, const char* charsSet );
 */
#define Apl_removeTrailingChars         _Apl_removeTrailingChars



#ifdef __cplusplus
}
#endif
/*--------------------------------------------------------------------------*/
#endif  /* end _apl_tokenizers_stripapi_h_ */