fnet_stdlib.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2016 by Andrey Butok. FNET Community.
00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
00005 *
00006 ***************************************************************************
00007 *
00008 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00009 *  not use this file except in compliance with the License.
00010 *  You may obtain a copy of the License at
00011 *
00012 *  http://www.apache.org/licenses/LICENSE-2.0
00013 *
00014 *  Unless required by applicable law or agreed to in writing, software
00015 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00016 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017 *  See the License for the specific language governing permissions and
00018 *  limitations under the License.
00019 *
00020 **********************************************************************/
00021 /*!
00022 *
00023 * @file fnet_stdlib.h
00024 *
00025 * @brief Standard functions API.
00026 *
00027 ***************************************************************************/
00028 
00029 #ifndef _FNET_STDLIB_H_
00030 
00031 #define _FNET_STDLIB_H_
00032 
00033 /*! @addtogroup fnet_stdlib
00034 * The standard library defines general purpose functions, including string converting, searching and other data manipulations.
00035 */
00036 
00037 /*! @{ */
00038 
00039 #include <stdarg.h> /* For va_list etc.*/
00040 #include <string.h> /* In case of alternative functions */
00041 
00042 /**************************************************************************/ /*!
00043  * @def FNET_NULL
00044  * @brief NULL pointer.
00045  * @showinitializer
00046  ******************************************************************************/
00047 #define FNET_NULL       (0)
00048 
00049 /**************************************************************************/ /*!
00050  * @def FNET_RAND_MAX
00051  * @brief The maximum number returned by @ref fnet_rand().
00052  * @showinitializer
00053  ******************************************************************************/
00054 #define FNET_RAND_MAX (32767u)
00055 
00056 /**************************************************************************/ /*!
00057  * @brief Unsigned integer type representing the size in bytes.
00058  ******************************************************************************/
00059 typedef unsigned long fnet_size_t;
00060 
00061 /**************************************************************************/ /*!
00062  * @brief Unsigned integer type representing the bit flag.
00063  ******************************************************************************/
00064 typedef unsigned int fnet_flag_t;
00065 
00066 /**************************************************************************/ /*!
00067  * @brief Unsigned integer type representing the index.
00068  ******************************************************************************/
00069 typedef unsigned int fnet_index_t;
00070 
00071 /**************************************************************************/ /*!
00072  * @brief Type representing the charecter.
00073  ******************************************************************************/
00074 typedef char fnet_char_t;
00075 
00076 /**************************************************************************/ /*!
00077  * @brief Boolean type.
00078  ******************************************************************************/
00079 typedef enum
00080 {
00081     FNET_FALSE = 0, /**< @brief FALSE Boolean value.*/
00082     FNET_TRUE  = 1  /**< @brief TRUE Boolean value.*/
00083 } fnet_bool_t;
00084 
00085 /**************************************************************************/ /*!
00086  * @brief General return codes, used by most of API functions.
00087  ******************************************************************************/
00088 typedef enum
00089 {
00090     FNET_OK  = (0), /**< No error.
00091                      */
00092     FNET_ERR = (-1) /**< There is error.
00093                      */
00094 } fnet_return_t;
00095 
00096 #if defined(__cplusplus)
00097 extern "C" {
00098 #endif
00099 
00100 /***************************************************************************/ /*!
00101  *
00102  * @brief    Copies bytes in memory.
00103  *
00104  * @param to_ptr      Pointer to the memory location to copy to.
00105  *
00106  * @param from_ptr       Pointer to the memory location to copy from.
00107  *
00108  * @param number_of_bytes         Number of bytes to copy.
00109  *
00110  * @see FNET_CFG_OVERLOAD_MEMCPY
00111  ******************************************************************************
00112  *
00113  * This function copies @c number_of_bytes bytes from
00114  * memory area pointed by @c from_ptr to memory area pointed by @c to_ptr.@n
00115  * You may overload it by own implementation, using @ref FNET_CFG_OVERLOAD_MEMCPY.
00116  *
00117  ******************************************************************************/
00118 #if !FNET_CFG_OVERLOAD_MEMCPY
00119 void fnet_memcpy(FNET_COMP_PACKED_VAR void *to_ptr, FNET_COMP_PACKED_VAR const void *from_ptr, fnet_size_t number_of_bytes);
00120 #endif
00121 
00122 /***************************************************************************/ /*!
00123  *
00124  * @brief    Relocates function in memory.
00125  *
00126  * @param to_buf_ptr      Pointer to the memory location to copy to.
00127  *
00128  * @param from_func_ptr       Pointer to the function to be relocated
00129  *
00130  * @param to_buf_size         Number of bytes to copy.
00131  *
00132  * @return          This function returns new pointer to the relocated function.
00133  ******************************************************************************
00134  *
00135  * This function copies @c to_buf_size bytes from
00136  * memory area pointed by @c from_func_ptr to memory area pointed by @c to_buf_ptr.@n
00137  * It is used for a function relocation from Flash to RAM.
00138  *
00139  ******************************************************************************/
00140 void *fnet_memcpy_func(void *to_buf_ptr, const void *from_func_ptr, fnet_size_t to_buf_size);
00141 
00142 /***************************************************************************/ /*!
00143  *
00144  * @brief           Sets bytes in memory.
00145  *
00146  * @param dest      Pointer to the buffer to be set.
00147  *
00148  * @param value     Value to be set. @n
00149  *                  The value is passed as an @c int, but the function converts
00150  *                  it to @c fnet_uint8_t.
00151  *
00152  * @param n         Number of bytes to be set.
00153  *
00154  * @see fnet_memset_zero()
00155  *
00156  ******************************************************************************
00157  *
00158  * This function sets the first @c n bytes of the memory area pointed to by
00159  * @c dest with the constant byte @c value.
00160  *
00161  ******************************************************************************/
00162 void fnet_memset(void *dest, fnet_uint8_t value, fnet_size_t n);
00163 
00164 /***************************************************************************/ /*!
00165  *
00166  * @brief           Sets bytes in memory to zeros.
00167  *
00168  * @param dest      Pointer to the buffer to be set.
00169  *
00170  * @param n         Number of bytes to be set.
00171  *
00172  * @see fnet_memset()
00173  *
00174  ******************************************************************************
00175  *
00176  * This function sets the first @c n bytes of the memory area pointed to by
00177  * @c dest with zeros.
00178  *
00179  ******************************************************************************/
00180 void fnet_memset_zero(void *dest, fnet_size_t n );
00181 
00182 /***************************************************************************/ /*!
00183  *
00184  * @brief           Compares memory areas.
00185  *
00186  * @param src1      Pointer to the memory buffer to compare.
00187  *
00188  * @param src2      Pointer to the memory buffer to compare.
00189  *
00190  * @param count     Number of bytes to compare.
00191  *
00192  * @return          This function returns zero if two buffers are identical,
00193  *                  otherwise returns @c 1.
00194  *
00195  ******************************************************************************
00196  *
00197  * This function compares the first @c n bytes of the memory buffer pointed
00198  * by @c src1 to the first @c count bytes pointed by @c src2, returning zero if
00199  * they all match, otherwise returns @c 1.
00200  *
00201  ******************************************************************************/
00202 fnet_int32_t fnet_memcmp(const void *src1, const void *src2, fnet_size_t count );
00203 
00204 /***************************************************************************/ /*!
00205  *
00206  * @brief           Calculates the length of a string.
00207  *
00208  * @param str       Pointer to the null-terminated string to be examined.
00209  *
00210  * @return          This function returns the number of characters in @c str.
00211  *
00212  ******************************************************************************
00213  *
00214  * This function computes the number of bytes in the string to which @c str
00215  * points, not including the terminating null byte.
00216  *
00217  ******************************************************************************/
00218 fnet_size_t fnet_strlen (const fnet_char_t *str);
00219 
00220 /***************************************************************************/ /*!
00221  *
00222  * @brief           Concatenates two strings.
00223  *
00224  * @param dest      Pointer to the null-terminated string to append to.
00225  *
00226  * @param src       Pointer to the null-terminated string to copy to
00227  *                  the end of @c dest.
00228  *
00229  ******************************************************************************
00230  *
00231  * This function appends a copy of the string pointed to by @c src to the end
00232  * of the string pointed to by  @c dest. @n
00233  * The resulting string is null-terminated.
00234  *
00235  ******************************************************************************/
00236 void fnet_strcat (fnet_char_t *dest, const fnet_char_t *src);
00237 
00238 /***************************************************************************/ /*!
00239  *
00240  * @brief           Concatenates a string with part of another.
00241  *
00242  * @param dest      Pointer to the null-terminated string to append to.
00243  *
00244  * @param src       Pointer to the null-terminated string to copy to
00245  *                  the end of @c dest.
00246  *
00247  * @param n         Maximum number of characters to be appended.
00248  *
00249  ******************************************************************************
00250  *
00251  * This function appends a copy of the string pointed to by @c src to the end
00252  * of the string pointed to by  @c dest. If the length of the @c src string
00253  * is less than @c n, only the content up to the terminating null-character
00254  * is copied. @n
00255  * The resulting string is null-terminated.
00256  *
00257  ******************************************************************************/
00258 void fnet_strncat (fnet_char_t *dest, const fnet_char_t *src, fnet_size_t n);
00259 
00260 /***************************************************************************/ /*!
00261  *
00262  * @brief           Copies a string.
00263  *
00264  * @param dest      Pointer to the destination buffer where the content is
00265  *                  to be copied.
00266  *
00267  * @param src       Pointer to the null-terminated string to be copied.
00268  *
00269  ******************************************************************************
00270  *
00271  * This function copies the string pointed by @c src into the buffer pointed
00272  * by @c dest, including the terminating null character.
00273  *
00274  ******************************************************************************/
00275 void fnet_strcpy (fnet_char_t *dest, const fnet_char_t *src);
00276 
00277 /***************************************************************************/ /*!
00278  *
00279  * @brief           Copies part of a string.
00280  *
00281  * @param dest      Pointer to the destination buffer where the content is
00282  *                  to be copied.
00283  *
00284  * @param src       Pointer to the null-terminated string to be copied.
00285  *
00286  * @param n         Maximum number of characters to be copied.
00287  *
00288  ******************************************************************************
00289  *
00290  * This function copies the first @c n characters of the string pointed
00291  * by @c src into the buffer pointed by @c dest.@n
00292  * The result string is null-terminated.
00293  *
00294  ******************************************************************************/
00295 void fnet_strncpy( fnet_char_t *dest, const fnet_char_t *src, fnet_size_t n );
00296 
00297 /***************************************************************************/ /*!
00298  *
00299  * @brief           Locates last occurrence of a character in a string.
00300  *
00301  * @param str       Pointer to the null-terminated string to be analyzed.
00302  *
00303  * @param chr       Character to search for.
00304  *
00305  * @return          This function returns the pointer to the found character
00306  *                  in @c str, or @ref FNET_NULL if no such character is found.
00307  *
00308  ******************************************************************************
00309  *
00310  * This function finds the last occurrence of the character @n chr
00311  * in the string pointed to by @c str..
00312  *
00313  ******************************************************************************/
00314 fnet_char_t *fnet_strrchr( const fnet_char_t *str, fnet_char_t chr );
00315 
00316 /***************************************************************************/ /*!
00317  *
00318  * @brief           Locates first occurrence of a character in a string.
00319  *
00320  * @param str       Pointer to the null-terminated string to be analyzed.
00321  *
00322  * @param chr       Character to search for.
00323  *
00324  * @return          This function returns the pointer to the found character
00325  *                  in @c str, or @ref FNET_NULL if no such character is found.
00326  *
00327  ******************************************************************************
00328  *
00329  * This function finds the first occurrence of the character @n chr
00330  * in the string pointed to by @c str.
00331  *
00332  ******************************************************************************/
00333 fnet_char_t *fnet_strchr(const fnet_char_t *str, fnet_char_t chr );
00334 
00335 /***************************************************************************/ /*!
00336  *
00337  * @brief           Locates a substring.
00338  *
00339  * @param str       Pointer to the null-terminated string to be analyzed.
00340  *
00341  * @param substr    Pointer to the null-terminated string to search for.
00342  *
00343  * @return          This function returns pointer to the first occurrence
00344  *                  in @c str of the entire sequence of characters
00345  *                  specified in @c substr.
00346  *
00347  ******************************************************************************
00348  *
00349  * This function finds the first occurrence of the substring @c substr
00350  * (excluding the terminating null byte) in the string @c str.
00351  *
00352  ******************************************************************************/
00353 fnet_char_t *fnet_strstr( const fnet_char_t *str, const fnet_char_t *substr );
00354 
00355 /***************************************************************************/ /*!
00356  *
00357  * @brief           Compares two strings.
00358  *
00359  * @param str1      Pointer to the null-terminated string to be compared.
00360  *
00361  * @param str2      Pointer to the null-terminated string to be compared.
00362  *
00363  * @return          This function returns zero if two strings are identical,
00364  *                  otherwise returns the difference between the first
00365  *                  two differing characters.
00366  *
00367  ******************************************************************************
00368  *
00369  * This function compares the two strings @c str1 and @c str2, returning zero if
00370  * they all match or the difference between the first two differing characters.
00371  *
00372  ******************************************************************************/
00373 fnet_int32_t fnet_strcmp( const fnet_char_t *str1, const fnet_char_t *str2 );
00374 
00375 /***************************************************************************/ /*!
00376  *
00377  * @brief           Compares part of two strings.
00378  *
00379  * @param str1      Pointer to the null-terminated string to be compared.
00380  *
00381  * @param str2      Pointer to the null-terminated string to be compared.
00382  *
00383  * @param n         Maximum number of characters to compare.
00384  *
00385  * @return          This function returns zero if @c n characters of
00386  *                  two strings are identical,
00387  *                  otherwise returns the difference between the first
00388  *                  two differing characters.
00389  *
00390  ******************************************************************************
00391  *
00392  * This function compares not more than @c n characters (characters that
00393  * follow a null byte are not compared) from the two strings @c str1 and
00394  * @c str2, returning zero if they all match or the difference between
00395  * the first two differing characters.
00396  *
00397  ******************************************************************************/
00398 fnet_int32_t fnet_strncmp( const fnet_char_t *str1, const fnet_char_t *str2, fnet_size_t n );
00399 
00400 /***************************************************************************/ /*!
00401  *
00402  * @brief           Compares two strings ignoring case.
00403  *
00404  * @param str1      Pointer to the null-terminated string to be compared.
00405  *
00406  * @param str2      Pointer to the null-terminated string to be compared.
00407  *
00408  * @return          This function returns an integer less than, equal to,
00409  *                  or greater than zero if @c str1 is found,
00410  *                  respectively, to be less than, to match, or be greater
00411  *                  than @c str2.
00412  *
00413  ******************************************************************************
00414  *
00415  * This function compares the two strings @c str1
00416  * and @c str2, ignoring the case of the characters. It returns an
00417  * integer less than, equal to, or greater than zero if @c str1 is found,
00418  * respectively, to be less than, to match, or be greater than @c str2.
00419  *
00420  ******************************************************************************/
00421 fnet_int32_t fnet_strcasecmp( const fnet_char_t *str1, const fnet_char_t *str2 );
00422 
00423 /***************************************************************************/ /*!
00424  *
00425  * @brief           Compares two strings, with additional terminator.
00426  *
00427  * @param in_str    Pointer to the null or @c splitter terminated string to be compared.
00428  *
00429  * @param name      Pointer to the null-terminated string to be compared.
00430  *
00431  * @param splitter  Additional terminator that can be used in @c str.
00432  *
00433  * @return          This function returns zero if two strings are identical,
00434  *                  otherwise returns the difference between the first
00435  *                  two differing characters.
00436  *
00437  ******************************************************************************
00438  *
00439  * This function compares the two strings @c in_str and @c name, returning zero if
00440  * they all match or the difference between the first two differing characters.@n
00441  * The @c name string can be terminated by null or @c splitter character.
00442  *
00443  ******************************************************************************/
00444 fnet_int32_t fnet_strcmp_splitter( const fnet_char_t *in_str, const fnet_char_t *name, fnet_char_t splitter);
00445 
00446 /***************************************************************************/ /*!
00447  *
00448  * @brief           Converts string to unsigned long integer.
00449  *
00450  * @param str       Pointer to the null-terminated string to be interpreted .
00451  *
00452  * @param ptr       Pointer to a pointer to character that will be set to
00453  *                  the character immediately following the unsigned long
00454  *                  integer in the string.  If no integer can be formed,
00455  *                  it points to the first wrong character.
00456  *
00457  * @param base      Base of the interpreted integer value. If it equals to 0,
00458  *                  it will be set to the default value 10.
00459  *
00460  * @return          This function returns integer value corresponding to the
00461  *                  contents of @c str on success. If no conversion can be
00462  *                  performed, @c 0 is returned.
00463  *
00464  ******************************************************************************
00465  *
00466  * This function converts a string to an unsigned long integer.@n
00467  * The string to be converted can contain the digits '0' to '9'.
00468  * Depending on the base, the string can also contain letters representing
00469  * digits greater than 9.
00470  *
00471  ******************************************************************************/
00472 fnet_uint32_t fnet_strtoul (const fnet_char_t *str, fnet_char_t **ptr, fnet_size_t base);
00473 
00474 /***************************************************************************/ /*!
00475  *
00476  * @brief    Breaks a string into a sequence of tokens.
00477  *
00478  * @param str           The string from which to extract tokens (null-terminated).
00479  *
00480  * @param delimiter     The string that contains a set of delimiter
00481  *                      characters (null-terminated).
00482  *
00483  * @param last          Return parameter used by @ref fnet_strtok_r() to record
00484  *                      its progress through @c str. @n
00485  *                      This pointer, must be the same while parsing the
00486  *                      same string.
00487  *
00488  * @return       This function returns a pointer to the next token in @c str.
00489  *               If there are no remaining tokens, it returns a @ref FNET_NULL
00490  *               pointer.
00491  *
00492  ******************************************************************************
00493  *
00494  * This function parses the string  @c str  into  tokens. @n
00495  * The  first function call should have @c str as its first argument. Subse-
00496  * quent calls should have the first  argument  set  to  @ref FNET_NULL.  Each  call
00497  * returns  a  pointer  to the next token, or @ref FNET_NULL when no more tokens are
00498  * found. @n
00499  * The function also updates the @c last parameter with the starting address
00500  * of the token following the first occurrence of the @c delimiter parameter. @n
00501  * The @c delimiter string may be different for each call.
00502  *
00503  ******************************************************************************/
00504 fnet_char_t *fnet_strtok_r(fnet_char_t *str, const fnet_char_t *delimiter, fnet_char_t **last);
00505 
00506 /***************************************************************************/ /*!
00507  *
00508  * @brief           Converts letter to lower case.
00509  *
00510  * @param to_lower   Letter to be converted to lower case, if possible.
00511  *
00512  * @return          This function returns converted letter.
00513  *
00514  ******************************************************************************
00515  *
00516  *  This function converts an uppercase letter to the corresponding
00517  * lowercase letter.
00518  *
00519  ******************************************************************************/
00520 fnet_char_t fnet_tolower( fnet_char_t to_lower );
00521 
00522 /***************************************************************************/ /*!
00523  *
00524  * @brief           Generates a pseudo-random number
00525  *
00526  * @return          Pseudo-random number in the range betwenn 0 to @ref FNET_RAND_MAX
00527  *
00528  ******************************************************************************
00529  *
00530  *  This function generates a pseudo-random number in the range betwenn 0 to @ref FNET_RAND_MAX
00531  *
00532  ******************************************************************************/
00533 fnet_uint32_t fnet_rand( void );
00534 
00535 /***************************************************************************/ /*!
00536  *
00537  * @brief           Initializes the pseudo-random number generator
00538  *
00539  * @param seed      Seed for the pseudo-random number generator
00540  *
00541  ******************************************************************************
00542  *
00543  *  This function initializes the pseudo-random generator with the seed argument
00544  *
00545  ******************************************************************************/
00546 void fnet_srand( fnet_uint32_t seed );
00547 
00548 #if defined(__cplusplus)
00549 }
00550 #endif
00551 
00552 /*! @} */
00553 
00554 #endif /* _FNET_STDLIB_H_ */