home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Servidores / apache_2.2.8-win32-x86-no_ssl.msi / Data1.cab / _6AA067F702413903575341EA8F062282 < prev    next >
Text File  |  2006-11-17  |  14KB  |  360 lines
  1. /* Licensed to the Apache Software Foundation (ASF) under one or more
  2.  * contributor license agreements.  See the NOTICE file distributed with
  3.  * this work for additional information regarding copyright ownership.
  4.  * The ASF licenses this file to You under the Apache License, Version 2.0
  5.  * (the "License"); you may not use this file except in compliance with
  6.  * the License.  You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. /* Portions of this file are covered by */
  18. /* -*- mode: c; c-file-style: "k&r" -*-
  19.  
  20.   strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
  21.   Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
  22.  
  23.   This software is provided 'as-is', without any express or implied
  24.   warranty.  In no event will the authors be held liable for any damages
  25.   arising from the use of this software.
  26.  
  27.   Permission is granted to anyone to use this software for any purpose,
  28.   including commercial applications, and to alter it and redistribute it
  29.   freely, subject to the following restrictions:
  30.  
  31.   1. The origin of this software must not be misrepresented; you must not
  32.      claim that you wrote the original software. If you use this software
  33.      in a product, an acknowledgment in the product documentation would be
  34.      appreciated but is not required.
  35.   2. Altered source versions must be plainly marked as such, and must not be
  36.      misrepresented as being the original software.
  37.   3. This notice may not be removed or altered from any source distribution.
  38. */
  39.  
  40. #ifndef APR_STRINGS_H
  41. #define APR_STRINGS_H
  42.  
  43. /**
  44.  * @file apr_strings.h
  45.  * @brief APR Strings library
  46.  */
  47.  
  48. #include "apr.h"
  49. #include "apr_errno.h"
  50. #include "apr_pools.h"
  51. #define APR_WANT_IOVEC
  52. #include "apr_want.h"
  53.  
  54. #if APR_HAVE_STDARG_H
  55. #include <stdarg.h>
  56. #endif
  57.  
  58. #ifdef __cplusplus
  59. extern "C" {
  60. #endif /* __cplusplus */
  61.  
  62. /**
  63.  * @defgroup apr_strings String routines
  64.  * @ingroup APR 
  65.  * @{
  66.  */
  67.  
  68. /**
  69.  * Do a natural order comparison of two strings.
  70.  * @param a The first string to compare
  71.  * @param b The second string to compare
  72.  * @return Either <0, 0, or >0.  If the first string is less than the second
  73.  *          this returns <0, if they are equivalent it returns 0, and if the
  74.  *          first string is greater than second string it retuns >0.
  75.  */
  76. APR_DECLARE(int) apr_strnatcmp(char const *a, char const *b);
  77.  
  78. /**
  79.  * Do a natural order comparison of two strings ignoring the case of the 
  80.  * strings.
  81.  * @param a The first string to compare
  82.  * @param b The second string to compare
  83.  * @return Either <0, 0, or >0.  If the first string is less than the second
  84.  *         this returns <0, if they are equivalent it returns 0, and if the
  85.  *         first string is greater than second string it retuns >0.
  86.  */
  87. APR_DECLARE(int) apr_strnatcasecmp(char const *a, char const *b);
  88.  
  89. /**
  90.  * duplicate a string into memory allocated out of a pool
  91.  * @param p The pool to allocate out of
  92.  * @param s The string to duplicate
  93.  * @return The new string
  94.  */
  95. APR_DECLARE(char *) apr_pstrdup(apr_pool_t *p, const char *s);
  96.  
  97. /**
  98.  * Create a null-terminated string by making a copy of a sequence
  99.  * of characters and appending a null byte
  100.  * @param p The pool to allocate out of
  101.  * @param s The block of characters to duplicate
  102.  * @param n The number of characters to duplicate
  103.  * @return The new string
  104.  * @remark This is a faster alternative to apr_pstrndup, for use
  105.  *         when you know that the string being duplicated really
  106.  *         has 'n' or more characters.  If the string might contain
  107.  *         fewer characters, use apr_pstrndup.
  108.  */
  109. APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);
  110.  
  111. /**
  112.  * Duplicate at most n characters of a string into memory allocated 
  113.  * out of a pool; the new string will be NUL-terminated
  114.  * @param p The pool to allocate out of
  115.  * @param s The string to duplicate
  116.  * @param n The maximum number of characters to duplicate
  117.  * @return The new string
  118.  * @remark The amount of memory allocated from the pool is the length
  119.  *         of the returned string including the NUL terminator
  120.  */
  121. APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);
  122.  
  123. /**
  124.  * Duplicate a block of memory.
  125.  *
  126.  * @param p The pool to allocate from
  127.  * @param m The memory to duplicate
  128.  * @param n The number of bytes to duplicate
  129.  * @return The new block of memory
  130.  */
  131. APR_DECLARE(void *) apr_pmemdup(apr_pool_t *p, const void *m, apr_size_t n);
  132.  
  133. /**
  134.  * Concatenate multiple strings, allocating memory out a pool
  135.  * @param p The pool to allocate out of
  136.  * @param ... The strings to concatenate.  The final string must be NULL
  137.  * @return The new string
  138.  */
  139. APR_DECLARE_NONSTD(char *) apr_pstrcat(apr_pool_t *p, ...);
  140.  
  141. /**
  142.  * Concatenate multiple strings specified in a writev-style vector
  143.  * @param p The pool from which to allocate
  144.  * @param vec The strings to concatenate
  145.  * @param nvec The number of strings to concatenate
  146.  * @param nbytes (output) strlen of new string (pass in NULL to omit)
  147.  * @return The new string
  148.  */
  149. APR_DECLARE(char *) apr_pstrcatv(apr_pool_t *p, const struct iovec *vec,
  150.                                  apr_size_t nvec, apr_size_t *nbytes);
  151.  
  152. /**
  153.  * printf-style style printing routine.  The data is output to a string 
  154.  * allocated from a pool
  155.  * @param p The pool to allocate out of
  156.  * @param fmt The format of the string
  157.  * @param ap The arguments to use while printing the data
  158.  * @return The new string
  159.  */
  160. APR_DECLARE(char *) apr_pvsprintf(apr_pool_t *p, const char *fmt, va_list ap);
  161.  
  162. /**
  163.  * printf-style style printing routine.  The data is output to a string 
  164.  * allocated from a pool
  165.  * @param p The pool to allocate out of
  166.  * @param fmt The format of the string
  167.  * @param ... The arguments to use while printing the data
  168.  * @return The new string
  169.  */
  170. APR_DECLARE_NONSTD(char *) apr_psprintf(apr_pool_t *p, const char *fmt, ...)
  171.         __attribute__((format(printf,2,3)));
  172.  
  173. /**
  174.  * Copy up to dst_size characters from src to dst; does not copy
  175.  * past a NUL terminator in src, but always terminates dst with a NUL
  176.  * regardless.
  177.  * @param dst The destination string
  178.  * @param src The source string
  179.  * @param dst_size The space available in dst; dst always receives
  180.  *                 NUL termination, so if src is longer than
  181.  *                 dst_size, the actual number of characters copied is
  182.  *                 dst_size - 1.
  183.  * @return Pointer to the NUL terminator of the destination string, dst
  184.  * @remark
  185.  * <PRE>
  186.  * Note the differences between this function and strncpy():
  187.  *  1) strncpy() doesn't always NUL terminate; apr_cpystrn() does.
  188.  *  2) strncpy() pads the destination string with NULs, which is often 
  189.  *     unnecessary; apr_cpystrn() does not.
  190.  *  3) strncpy() returns a pointer to the beginning of the dst string;
  191.  *     apr_cpystrn() returns a pointer to the NUL terminator of dst, 
  192.  *     to allow a check for truncation.
  193.  * </PRE>
  194.  */
  195. APR_DECLARE(char *) apr_cpystrn(char *dst, const char *src,
  196.                                 apr_size_t dst_size);
  197.  
  198. /**
  199.  * Strip spaces from a string
  200.  * @param dest The destination string.  It is okay to modify the string
  201.  *             in place.  Namely dest == src
  202.  * @param src The string to rid the spaces from.
  203.  * @return The destination string, dest.
  204.  */
  205. APR_DECLARE(char *) apr_collapse_spaces(char *dest, const char *src);
  206.  
  207. /**
  208.  * Convert the arguments to a program from one string to an array of 
  209.  * strings terminated by a NULL pointer
  210.  * @param arg_str The arguments to convert
  211.  * @param argv_out Output location.  This is a pointer to an array of strings.
  212.  * @param token_context Pool to use.
  213.  */
  214. APR_DECLARE(apr_status_t) apr_tokenize_to_argv(const char *arg_str,
  215.                                                char ***argv_out,
  216.                                                apr_pool_t *token_context);
  217.  
  218. /**
  219.  * Split a string into separate null-terminated tokens.  The tokens are 
  220.  * delimited in the string by one or more characters from the sep
  221.  * argument.
  222.  * @param str The string to separate; this should be specified on the
  223.  *            first call to apr_strtok() for a given string, and NULL
  224.  *            on subsequent calls.
  225.  * @param sep The set of delimiters
  226.  * @param last Internal state saved by apr_strtok() between calls.
  227.  * @return The next token from the string
  228.  */
  229. APR_DECLARE(char *) apr_strtok(char *str, const char *sep, char **last);
  230.  
  231. /**
  232.  * @defgroup APR_Strings_Snprintf snprintf implementations
  233.  * @warning
  234.  * These are snprintf implementations based on apr_vformatter().
  235.  *
  236.  * Note that various standards and implementations disagree on the return
  237.  * value of snprintf, and side-effects due to %n in the formatting string.
  238.  * apr_snprintf (and apr_vsnprintf) behaves as follows:
  239.  *
  240.  * Process the format string until the entire string is exhausted, or
  241.  * the buffer fills.  If the buffer fills then stop processing immediately
  242.  * (so no further %n arguments are processed), and return the buffer
  243.  * length.  In all cases the buffer is NUL terminated. It will return the
  244.  * number of characters inserted into the buffer, not including the
  245.  * terminating NUL. As a special case, if len is 0, apr_snprintf will
  246.  * return the number of characters that would have been inserted if
  247.  * the buffer had been infinite (in this case, *buffer can be NULL)
  248.  *
  249.  * In no event does apr_snprintf return a negative number.
  250.  * @{
  251.  */
  252.  
  253. /**
  254.  * snprintf routine based on apr_vformatter.  This means it understands the
  255.  * same extensions.
  256.  * @param buf The buffer to write to
  257.  * @param len The size of the buffer
  258.  * @param format The format string
  259.  * @param ... The arguments to use to fill out the format string.
  260.  */
  261. APR_DECLARE_NONSTD(int) apr_snprintf(char *buf, apr_size_t len,
  262.                                      const char *format, ...)
  263.         __attribute__((format(printf,3,4)));
  264.  
  265. /**
  266.  * vsnprintf routine based on apr_vformatter.  This means it understands the
  267.  * same extensions.
  268.  * @param buf The buffer to write to
  269.  * @param len The size of the buffer
  270.  * @param format The format string
  271.  * @param ap The arguments to use to fill out the format string.
  272.  */
  273. APR_DECLARE(int) apr_vsnprintf(char *buf, apr_size_t len, const char *format,
  274.                                va_list ap);
  275. /** @} */
  276.  
  277. /**
  278.  * create a string representation of an int, allocated from a pool
  279.  * @param p The pool from which to allocate
  280.  * @param n The number to format
  281.  * @return The string representation of the number
  282.  */
  283. APR_DECLARE(char *) apr_itoa(apr_pool_t *p, int n);
  284.  
  285. /**
  286.  * create a string representation of a long, allocated from a pool
  287.  * @param p The pool from which to allocate
  288.  * @param n The number to format
  289.  * @return The string representation of the number
  290.  */
  291. APR_DECLARE(char *) apr_ltoa(apr_pool_t *p, long n);
  292.  
  293. /**
  294.  * create a string representation of an apr_off_t, allocated from a pool
  295.  * @param p The pool from which to allocate
  296.  * @param n The number to format
  297.  * @return The string representation of the number
  298.  */
  299. APR_DECLARE(char *) apr_off_t_toa(apr_pool_t *p, apr_off_t n);
  300.  
  301. /**
  302.  * Convert a numeric string into an apr_off_t numeric value.
  303.  * @param offset The value of the parsed string.
  304.  * @param buf The string to parse. It may contain optional whitespace,
  305.  *   followed by an optional '+' (positive, default) or '-' (negative)
  306.  *   character, followed by an optional '0x' prefix if base is 0 or 16,
  307.  *   followed by numeric digits appropriate for base.
  308.  * @param end A pointer to the end of the valid character in buf. If
  309.  *   not NULL, it is set to the first invalid character in buf.
  310.  * @param base A numeric base in the range between 2 and 36 inclusive,
  311.  *   or 0.  If base is zero, buf will be treated as base ten unless its
  312.  *   digits are prefixed with '0x', in which case it will be treated as
  313.  *   base 16.
  314.  */
  315. APR_DECLARE(apr_status_t) apr_strtoff(apr_off_t *offset, const char *buf, 
  316.                                       char **end, int base);
  317.  
  318. /**
  319.  * parse a numeric string into a 64-bit numeric value
  320.  * @param buf The string to parse. It may contain optional whitespace,
  321.  *   followed by an optional '+' (positive, default) or '-' (negative)
  322.  *   character, followed by an optional '0x' prefix if base is 0 or 16,
  323.  *   followed by numeric digits appropriate for base.
  324.  * @param end A pointer to the end of the valid character in buf. If
  325.  *   not NULL, it is set to the first invalid character in buf.
  326.  * @param base A numeric base in the range between 2 and 36 inclusive,
  327.  *   or 0.  If base is zero, buf will be treated as base ten unless its
  328.  *   digits are prefixed with '0x', in which case it will be treated as
  329.  *   base 16.
  330.  * @return The numeric value of the string.  On overflow, errno is set
  331.  * to ERANGE.
  332.  */
  333. APR_DECLARE(apr_int64_t) apr_strtoi64(const char *buf, char **end, int base);
  334.  
  335. /**
  336.  * parse a base-10 numeric string into a 64-bit numeric value.
  337.  * Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
  338.  * @param buf The string to parse
  339.  * @return The numeric value of the string
  340.  */
  341. APR_DECLARE(apr_int64_t) apr_atoi64(const char *buf);
  342.  
  343. /**
  344.  * Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t,
  345.  * as bytes, K, M, T, etc, to a four character compacted human readable string.
  346.  * @param size The size to format
  347.  * @param buf The 5 byte text buffer (counting the trailing null)
  348.  * @return The buf passed to apr_strfsize()
  349.  * @remark All negative sizes report '  - ', apr_strfsize only formats positive values.
  350.  */
  351. APR_DECLARE(char *) apr_strfsize(apr_off_t size, char *buf);
  352.  
  353. /** @} */
  354.  
  355. #ifdef __cplusplus
  356. }
  357. #endif
  358.  
  359. #endif  /* !APR_STRINGS_H */
  360.