Pileus Git - ~andy/fetchmail/blob - trio/doc/doc_static.h

   1 /*************************************************************************
   2  *
   3  * $Id: doc_static.h,v 1.1 2001/12/27 17:29:20 breese Exp $
   4  *
   5  * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg.
   6  *
   7  * Permission to use, copy, modify, and distribute this software for any
   8  * purpose with or without fee is hereby granted, provided that the above
   9  * copyright notice and this permission notice appear in all copies.
  10  *
  11  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  12  * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  13  * MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND
  14  * CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER.
  15  *
  16  ************************************************************************/
  17
  18 /** @addtogroup StaticStrings Static String Functions.
  19 Replacements for the standard C string functions.
  20
  21 @b SYNOPSIS
  22
  23 @verbatim
  24 cc ... -ltrio -lm
  25
  26 #include <triostr.h>
  27 @endverbatim
  28
  29 @b DESCRIPTION
  30
  31 This package renames, fixes, and extends the standard C string handling
  32 functions.
  33
  34 @b Naming
  35
  36 Renaming is done to provide more clear names, to provide a consistant naming
  37 and argument policy, and to hide portability issues.
  38
  39 @li All functions starts with "trio_".
  40 @li Target is always the first argument, if present, except where the target
  41 is optional, such as @ref trio_to_double.
  42 @li Functions requiring a size for target includes "_max" in its name, and
  43 the size is always the second argument.
  44 @li Functions performing case-sensitive operations includes "_case" in its
  45 name.
  46
  47 @b Fixing
  48
  49 Fixing is done to avoid subtle error conditions.
  50 For example, @c strncpy does not terminate the result with a zero if the
  51 source string is bigger than the maximal length, so technically the result
  52 is not a C string anymore. @ref trio_copy_max makes sure that the result
  53 is zero terminated.
  54
  55 @b Extending
  56
  57 Extending is done to provide a richer set of fundamental functions.
  58 This includes functionality such as wildcard matching ( @c trio_match )
  59 and calculation of hash values ( @c trio_hash ).
  60
  61 */