Changeset 5273eb6 in mainline


Ignore:
Timestamp:
2011-07-19T00:12:36Z (14 years ago)
Author:
Petr Koupy <petr.koupy@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
087c4c56
Parents:
ca1f1ec
Message:

Added comments to string.h functions (no change in functionality).

Location:
uspace/lib/posix
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • TabularUnified uspace/lib/posix/string.c

    rca1f1ec r5273eb6  
    3131 * @{
    3232 */
    33 /** @file
     33/** @file String manipulation.
    3434 */
    3535
    … …  
    4848
    4949/**
    50  * Returns true if s2 is a prefix of s1.
    51  *
    52  * @param s1
    53  * @param s2
    54  * @return
     50 * Decides whether s2 is a prefix of s1.
     51 *
     52 * @param s1 String in which to look for a prefix.
     53 * @param s2 Prefix string to look for.
     54 * @return True if s2 is a prefix of s1, false otherwise.
    5555 */
    5656static bool begins_with(const char *s1, const char *s2)
    … …  
    6969 * if no occurence is found.
    7070 *
    71  * @param s1
    72  * @param s2
    73  * @return
     71 * @param s1 String in which to look for the bytes.
     72 * @param s2 String of bytes to look for.
     73 * @return Pointer to the found byte on success, pointer to the
     74 *     string terminator otherwise.
    7475 */
    7576static char *strpbrk_null(const char *s1, const char *s2)
    … …  
    8384
    8485/**
    85  *
    86  * @param dest
    87  * @param src
    88  * @return
    89  */
    90 char *posix_strcpy(char *dest, const char *src)
     86 * Copy a string.
     87 *
     88 * @param dest Destination pre-allocated buffer.
     89 * @param src Source string to be copied.
     90 * @return Pointer to the destination buffer.
     91 */
     92char *posix_strcpy(char *restrict dest, const char *restrict src)
    9193{
    9294        posix_stpcpy(dest, src);
    … …  
    9597
    9698/**
    97  *
    98  * @param dest
    99  * @param src
    100  * @param n
    101  * @return
    102  */
    103 char *posix_strncpy(char *dest, const char *src, size_t n)
     99 * Copy fixed length string.
     100 *
     101 * @param dest Destination pre-allocated buffer.
     102 * @param src Source string to be copied.
     103 * @param n Number of bytes to be stored into destination buffer.
     104 * @return Pointer to the destination buffer.
     105 */
     106char *posix_strncpy(char *restrict dest, const char *restrict src, size_t n)
    104107{
    105108        posix_stpncpy(dest, src, n);
    … …  
    108111
    109112/**
    110  *
    111  * @param dest
    112  * @param src
    113  * @return Pointer to the nul character in the dest string
     113 * Copy a string.
     114 *
     115 * @param dest Destination pre-allocated buffer.
     116 * @param src Source string to be copied.
     117 * @return Pointer to the nul character in the destination string.
    114118 */
    115119char *posix_stpcpy(char *restrict dest, const char *restrict src)
    … …  
    132136
    133137/**
    134  *
    135  * @param dest
    136  * @param src
    137  * @param n
    138  * @return Pointer to the first written nul character or &dest[n]
     138 * Copy fixed length string.
     139 *
     140 * @param dest Destination pre-allocated buffer.
     141 * @param src Source string to be copied.
     142 * @param n Number of bytes to be stored into destination buffer.
     143 * @return Pointer to the first written nul character or &dest[n].
    139144 */
    140145char *posix_stpncpy(char *restrict dest, const char *restrict src, size_t n)
    … …  
    162167
    163168/**
    164  *
    165  * @param dest
    166  * @param src
    167  * @return
    168  */
    169 char *posix_strcat(char *dest, const char *src)
     169 * Concatenate two strings.
     170 *
     171 * @param dest String to which src shall be appended.
     172 * @param src String to be appended after dest.
     173 * @return Pointer to destination buffer.
     174 */
     175char *posix_strcat(char *restrict dest, const char *restrict src)
    170176{
    171177        assert(dest != NULL);
    … …  
    177183
    178184/**
    179  *
    180  * @param dest
    181  * @param src
    182  * @param n
    183  * @return
    184  */
    185 char *posix_strncat(char *dest, const char *src, size_t n)
     185 * Concatenate a string with part of another.
     186 *
     187 * @param dest String to which part of src shall be appended.
     188 * @param src String whose part shall be appended after dest.
     189 * @param n Number of bytes to append after dest.
     190 * @return Pointer to destination buffer.
     191 */
     192char *posix_strncat(char *restrict dest, const char *restrict src, size_t n)
    186193{
    187194        assert(dest != NULL);
    … …  
    195202
    196203/**
    197  *
    198  * @param dest
    199  * @param src
    200  * @param c
    201  * @param n
     204 * Copy limited number of bytes in memory.
     205 *
     206 * @param dest Destination buffer.
     207 * @param src Source buffer.
     208 * @param c Character after which the copying shall stop.
     209 * @param n Number of bytes that shall be copied if not stopped earlier by c.
    202210 * @return Pointer to the first byte after c in dest if found, NULL otherwise.
    203211 */
    204 void *posix_memccpy(void *dest, const void *src, int c, size_t n)
     212void *posix_memccpy(void *restrict dest, const void *restrict src, int c, size_t n)
    205213{
    206214        assert(dest != NULL);
    … …  
    223231
    224232/**
    225  *
    226  * @param s
    227  * @return Newly allocated string
     233 * Duplicate a string.
     234 *
     235 * @param s String to be duplicated.
     236 * @return Newly allocated copy of the string.
    228237 */
    229238char *posix_strdup(const char *s)
    … …  
    233242
    234243/**
    235  *
    236  * @param s
    237  * @param n
    238  * @return Newly allocated string of length at most n
     244 * Duplicate a specific number of bytes from a string.
     245 *
     246 * @param s String to be duplicated.
     247 * @param n Maximum length of the resulting string..
     248 * @return Newly allocated string copy of length at most n.
    239249 */
    240250char *posix_strndup(const char *s, size_t n)
    … …  
    255265
    256266/**
    257  *
    258  * @param mem1
    259  * @param mem2
    260  * @param n
     267 * Compare bytes in memory.
     268 *
     269 * @param mem1 First area of memory to be compared.
     270 * @param mem2 Second area of memory to be compared.
     271 * @param n Maximum number of bytes to be compared.
    261272 * @return Difference of the first pair of inequal bytes,
    262  *     or 0 if areas have the same content
     273 *     or 0 if areas have the same content.
    263274 */
    264275int posix_memcmp(const void *mem1, const void *mem2, size_t n)
    … …  
    280291
    281292/**
    282  *
    283  * @param s1
    284  * @param s2
    285  * @return
     293 * Compare two strings.
     294 *
     295 * @param s1 First string to be compared.
     296 * @param s2 Second string to be compared.
     297 * @return Difference of the first pair of inequal characters,
     298 *     or 0 if strings have the same content.
    286299 */
    287300int posix_strcmp(const char *s1, const char *s2)
    … …  
    294307
    295308/**
    296  *
    297  * @param s1
    298  * @param s2
    299  * @param n
    300  * @return
     309 * Compare part of two strings.
     310 *
     311 * @param s1 First string to be compared.
     312 * @param s2 Second string to be compared.
     313 * @param n Maximum number of characters to be compared.
     314 * @return Difference of the first pair of inequal characters,
     315 *     or 0 if strings have the same content.
    301316 */
    302317int posix_strncmp(const char *s1, const char *s2, size_t n)
    … …  
    318333
    319334/**
    320  *
    321  * @param mem
    322  * @param c
    323  * @param n
    324  * @return
     335 * Find byte in memory.
     336 *
     337 * @param mem Memory area in which to look for the byte.
     338 * @param c Byte to look for.
     339 * @param n Maximum number of bytes to be inspected.
     340 * @return Pointer to the specified byte on success,
     341 *     NULL pointer otherwise.
    325342 */
    326343void *posix_memchr(const void *mem, int c, size_t n)
    … …  
    339356
    340357/**
    341  *
    342  * @param s
    343  * @param c
    344  * @return
     358 * Scan string for a first occurence of a character.
     359 *
     360 * @param s String in which to look for the character.
     361 * @param c Character to look for.
     362 * @return Pointer to the specified character on success,
     363 *     NULL pointer otherwise.
    345364 */
    346365char *posix_strchr(const char *s, int c)
    … …  
    353372
    354373/**
    355  *
    356  * @param s
    357  * @param c
    358  * @return
     374 * Scan string for a last occurence of a character.
     375 *
     376 * @param s String in which to look for the character.
     377 * @param c Character to look for.
     378 * @return Pointer to the specified character on success,
     379 *     NULL pointer otherwise.
    359380 */
    360381char *posix_strrchr(const char *s, int c)
    … …  
    376397}
    377398
     399/**
     400 * Scan string for a first occurence of a character.
     401 *
     402 * @param s String in which to look for the character.
     403 * @param c Character to look for.
     404 * @return Pointer to the specified character on success, pointer to the
     405 *     string terminator otherwise.
     406 */
    378407char *gnu_strchrnul(const char *s, int c)
    379408{
    … …  
    388417
    389418/**
    390  *
    391  * @param s1
    392  * @param s2
    393  * @return
     419 * Scan a string for a first occurence of one of provided bytes.
     420 *
     421 * @param s1 String in which to look for the bytes.
     422 * @param s2 String of bytes to look for.
     423 * @return Pointer to the found byte on success,
     424 *     NULL pointer otherwise.
    394425 */
    395426char *posix_strpbrk(const char *s1, const char *s2)
    … …  
    403434
    404435/**
    405  *
    406  * @param s1
    407  * @param s2
    408  * @return
     436 * Get the length of a complementary substring.
     437 *
     438 * @param s1 String that shall be searched for complementary prefix.
     439 * @param s2 String of bytes that shall not occur in the prefix.
     440 * @return Length of the prefix.
    409441 */
    410442size_t posix_strcspn(const char *s1, const char *s2)
    … …  
    418450
    419451/**
    420  *
    421  * @param s1
    422  * @param s2
    423  * @return
     452 * Get length of a substring.
     453 *
     454 * @param s1 String that shall be searched for prefix.
     455 * @param s2 String of bytes that the prefix must consist of.
     456 * @return Length of the prefix.
    424457 */
    425458size_t posix_strspn(const char *s1, const char *s2)
    … …  
    438471
    439472/**
    440  *
    441  * @param s1
    442  * @param s2
    443  * @return
     473 * Find a substring.
     474 *
     475 * @param s1 String in which to look for a substring.
     476 * @param s2 Substring to look for.
     477 * @return Pointer to the first character of the substring in s1, or NULL if
     478 *     not found.
    444479 */
    445480char *posix_strstr(const char *s1, const char *s2)
    … …  
    467502
    468503/**
     504 * String comparison using collating information.
     505 *
    469506 * Currently ignores locale and just calls strcmp.
    470507 *
    471  * @param s1
    472  * @param s2
    473  * @return
     508 * @param s1 First string to be compared.
     509 * @param s2 Second string to be compared.
     510 * @return Difference of the first pair of inequal characters,
     511 *     or 0 if strings have the same content.
    474512 */
    475513int posix_strcoll(const char *s1, const char *s2)
    … …  
    482520
    483521/**
    484  * strcoll is equal to strcmp here, so this just makes a copy.
    485  *
    486  * @param s1
    487  * @param s2
    488  * @param n
    489  * @return
    490  */
    491 size_t posix_strxfrm(char *s1, const char *s2, size_t n)
     522 * Transform a string in such a way that the resulting string yields the same
     523 * results when passed to the strcmp as if the original string is passed to
     524 * the strcoll.
     525 *
     526 * Since strcoll is equal to strcmp here, this just makes a copy.
     527 *
     528 * @param s1 Transformed string.
     529 * @param s2 Original string.
     530 * @param n Maximum length of the transformed string.
     531 * @return Length of the transformed string.
     532 */
     533size_t posix_strxfrm(char *restrict s1, const char *restrict s2, size_t n)
    492534{
    493535        assert(s1 != NULL || n == 0);
    … …  
    504546
    505547/**
    506  *
    507  * @param errnum
    508  * @return
     548 * Get error message string.
     549 *
     550 * @param errnum Error code for which to obtain human readable string.
     551 * @return Error message.
    509552 */
    510553char *posix_strerror(int errnum)
    … …  
    518561
    519562/**
    520  *
    521  * @param errnum Error code
    522  * @param buf Buffer to store a human readable string to
    523  * @param bufsz Size of buffer pointed to by buf
    524  * @return
     563 * Get error message string.
     564 *
     565 * @param errnum Error code for which to obtain human readable string.
     566 * @param buf Buffer to store a human readable string to.
     567 * @param bufsz Size of buffer pointed to by buf.
     568 * @return Zero on success, errno otherwise.
    525569 */
    526570int posix_strerror_r(int errnum, char *buf, size_t bufsz)
    … …  
    541585
    542586/**
    543  *
    544  * @param s
    545  * @return
     587 * Get length of the string.
     588 *
     589 * @param s String which length shall be determined.
     590 * @return Length of the string.
    546591 */
    547592size_t posix_strlen(const char *s)
    … …  
    553598
    554599/**
    555  *
    556  * @param s
    557  * @param n
    558  * @return
     600 * Get limited length of the string.
     601 *
     602 * @param s String which length shall be determined.
     603 * @param n Maximum number of bytes that can be examined to determine length.
     604 * @return The lower of either string length or n limit.
    559605 */
    560606size_t posix_strnlen(const char *s, size_t n)
    … …  
    573619
    574620/**
    575  *
    576  * @param signum
    577  * @return
     621 * Get description of a signal.
     622 *
     623 * @param signum Signal number.
     624 * @return Human readable signal description.
    578625 */
    579626char *posix_strsignal(int signum)

  • TabularUnified uspace/lib/posix/string.h

    rca1f1ec r5273eb6  
    3131 * @{
    3232 */
    33 /** @file
     33/** @file String manipulation.
    3434 */
    3535
    … …  
    103103extern size_t posix_strnlen(const char *s, size_t n);
    104104
    105 /* Signal messages */
     105/* Signal Messages */
    106106extern char *posix_strsignal(int signum);
    107107
Note: See TracChangeset for help on using the changeset viewer.