os/ossrv/genericopenlibs/openenvcore/include/strings.dosc
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
sl@0
     1
/** @file  ../include/strings.h
sl@0
     2
@internalComponent
sl@0
     3
*/
sl@0
     4
sl@0
     5
/** @fn  bcmp(const void *b1, const void *b2, size_t length)
sl@0
     6
@param b1
sl@0
     7
@param b2
sl@0
     8
@param length
sl@0
     9
@return   bcmp function returns 0 if the byte sequences are equal and non-zero 
sl@0
    10
  otherwise.
sl@0
    11
sl@0
    12
  The bcmp function compares byte string b1 against byte string b2, returning zero if they are identical and non-zero otherwise. Both 
sl@0
    13
strings are assumed to be length bytes long. Zero-length strings are always identical.
sl@0
    14
sl@0
    15
 The strings may overlap.
sl@0
    16
sl@0
    17
Examples:
sl@0
    18
@code
sl@0
    19
#include <string.h>
sl@0
    20
#include <stdio.h>
sl@0
    21
int main()
sl@0
    22
{
sl@0
    23
   int ret = 0;
sl@0
    24
   ret = bcmp("a","a",1);               
sl@0
    25
   printf("bcmp(\"a\",\"a\",1) is %d",ret);
sl@0
    26
   ret = bcmp("abcd","abce",4); 
sl@0
    27
   printf("
sl@0
    28
bcmp(\"abcd\",\"abce\",1) is %d",ret);
sl@0
    29
   ret = bcmp("abc","xyz",0);
sl@0
    30
   printf("
sl@0
    31
bcmp(\"abc\",\"xyz\",0) is %d",ret);
sl@0
    32
   return 0;
sl@0
    33
}
sl@0
    34
sl@0
    35
@endcode
sl@0
    36
 Output
sl@0
    37
@code
sl@0
    38
bcmp("a","a",1) is 0
sl@0
    39
bcmp("abcd","abce",1) is -1
sl@0
    40
bcmp("abc","xyz",0) is 0
sl@0
    41
sl@0
    42
@endcode
sl@0
    43
@see memcmp()
sl@0
    44
@see strcasecmp()
sl@0
    45
@see strcmp()
sl@0
    46
@see strcoll()
sl@0
    47
@see strxfrm()
sl@0
    48
sl@0
    49
sl@0
    50
 
sl@0
    51
sl@0
    52
@publishedAll
sl@0
    53
@externallyDefinedApi
sl@0
    54
*/
sl@0
    55
sl@0
    56
/** @fn  bcopy(const void *src0, void *dst0, size_t length)
sl@0
    57
@param src0
sl@0
    58
@param dst0
sl@0
    59
@param length
sl@0
    60
sl@0
    61
  The bcopy function copies length bytes from string src0 to string dst0 . The two strings may overlap. If length is zero no bytes are copied.
sl@0
    62
sl@0
    63
Examples:
sl@0
    64
@code
sl@0
    65
#include <string.h>
sl@0
    66
#include <stdio.h>
sl@0
    67
int main()
sl@0
    68
{
sl@0
    69
    char dst[50];
sl@0
    70
    bcopy("Hello World",dst,12);        
sl@0
    71
    printf("Destination string after bcopy = %s
sl@0
    72
",dst);
sl@0
    73
    return 0;
sl@0
    74
}
sl@0
    75
sl@0
    76
@endcode
sl@0
    77
 Output
sl@0
    78
@code
sl@0
    79
Destination string after bcopy = Hello World
sl@0
    80
sl@0
    81
@endcode
sl@0
    82
@see memccpy()
sl@0
    83
@see memcpy()
sl@0
    84
@see memmove()
sl@0
    85
@see strcpy()
sl@0
    86
sl@0
    87
sl@0
    88
 
sl@0
    89
sl@0
    90
@publishedAll
sl@0
    91
@externallyDefinedApi
sl@0
    92
*/
sl@0
    93
sl@0
    94
/** @fn  bzero(void *b, size_t len)
sl@0
    95
@param b
sl@0
    96
@param len
sl@0
    97
sl@0
    98
  The bzero function
sl@0
    99
writes len zero bytes to the string b. If len is zero, bzero does nothing.
sl@0
   100
sl@0
   101
Examples:
sl@0
   102
@code
sl@0
   103
#include <string.h>
sl@0
   104
#include <stdio.h>
sl@0
   105
int main()
sl@0
   106
{
sl@0
   107
    char dst[50] = "abcdef";
sl@0
   108
    bzero(dst + 2, 2);
sl@0
   109
    if(!strcmp(dst, "ab")) printf("dst =  %s
sl@0
   110
",dst);
sl@0
   111
    if(!strcmp(dst+3, "")) printf("zeros added to dst string
sl@0
   112
");
sl@0
   113
    if(!strcmp(dst + 4, "ef")) printf("dst + 4 = %s
sl@0
   114
",dst);
sl@0
   115
    return 0;
sl@0
   116
}
sl@0
   117
sl@0
   118
@endcode
sl@0
   119
 Output
sl@0
   120
@code
sl@0
   121
dst =  ab
sl@0
   122
zeros added to dst string
sl@0
   123
dst + 4 = ab
sl@0
   124
sl@0
   125
@endcode
sl@0
   126
@see memset()
sl@0
   127
@see swab()
sl@0
   128
sl@0
   129
sl@0
   130
 
sl@0
   131
sl@0
   132
@publishedAll
sl@0
   133
@externallyDefinedApi
sl@0
   134
*/
sl@0
   135
sl@0
   136
/** @fn  ffs(int mask)
sl@0
   137
@param mask
sl@0
   138
sl@0
   139
Note: This description also covers the following functions -
sl@0
   140
 ffsl()  fls()  flsl() 
sl@0
   141
sl@0
   142
@return  
sl@0
   143
sl@0
   144
  The ffs and ffsl functions find the first bit set in mask and return the index of that bit.
sl@0
   145
sl@0
   146
 The fls and flsl functions find the last bit set in mask and return the index of that bit.
sl@0
   147
sl@0
   148
 Bits are numbered starting from 1, starting at the right-most
sl@0
   149
(least significant) bit.
sl@0
   150
A return value of zero from any of these functions means that the
sl@0
   151
argument was zero.
sl@0
   152
sl@0
   153
Examples:
sl@0
   154
@code
sl@0
   155
#include <string.h>
sl@0
   156
#include <stdio.h>
sl@0
   157
int main()
sl@0
   158
{
sl@0
   159
    int i = 0x10;
sl@0
   160
    int j = ffs(i);
sl@0
   161
    if(j == 5) printf("First bit position in 0x10 is %d
sl@0
   162
",j);
sl@0
   163
    return 0;
sl@0
   164
}
sl@0
   165
sl@0
   166
@endcode
sl@0
   167
 Output
sl@0
   168
@code
sl@0
   169
First bit position in 0x10 is 5
sl@0
   170
@endcode
sl@0
   171
 
sl@0
   172
 
sl@0
   173
sl@0
   174
@publishedAll
sl@0
   175
@externallyDefinedApi
sl@0
   176
*/
sl@0
   177
sl@0
   178
/** @fn  index(const char *p, int ch)
sl@0
   179
@param p
sl@0
   180
@param ch
sl@0
   181
Note: This description also covers the following functions -
sl@0
   182
 rindex() 
sl@0
   183
sl@0
   184
@return   The functions index and rindex return a pointer to the located character, or NULL if the character does not appear in the string.
sl@0
   185
sl@0
   186
The  index function locates the first occurrence of  ch (converted to a char ) in the string pointed to by p. The terminating null character is considered part of the string; therefore if  ch is ‘\\0,’ the functions locate the terminating ‘\\0.’
sl@0
   187
sl@0
   188
The rindex function is identical to index, except it locates the last occurrence of ch.
sl@0
   189
sl@0
   190
Examples:
sl@0
   191
@code
sl@0
   192
#include <string.h>
sl@0
   193
#include <stdio.h>
sl@0
   194
int main()
sl@0
   195
{
sl@0
   196
    char one[50];
sl@0
   197
    char* ret;
sl@0
   198
    strcpy(one,"abcd");
sl@0
   199
    ret = index(one, ’c’);
sl@0
   200
    if(!strncmp(one+2,ret,1)) printf("index of \ ’c\ ’ in string \"abcd\" is %d \n",2);
sl@0
   201
    ret = index(one, ’z’);
sl@0
   202
    if(ret == NULL) printf("\ ’z\ ’ not found in string \"abcd\"\n");
sl@0
   203
    ret = index(one, ’\0’);
sl@0
   204
    if(!strncmp(one+4,ret,1)) printf("index of \ ’\ \0\ ’ in string \"abcd\" is %d\n",4);
sl@0
   205
    strcpy(one,"cdcab");
sl@0
   206
    ret = rindex(one, ’c’);
sl@0
   207
    if(!strncmp(one+2,ret,1)) printf("rindex of \ ’c\ ’ in string \"cscab\" is %d\n",2);
sl@0
   208
    strcpy(one,"dcab");
sl@0
   209
    ret = rindex(one, ’\0’);
sl@0
   210
    if(!strncmp(one+4,ret,1)) printf("index of \ ’\ \0\ ’ in string \"dcab\" is %d\n",4);
sl@0
   211
    return 0;
sl@0
   212
}
sl@0
   213
sl@0
   214
@endcode
sl@0
   215
 Output
sl@0
   216
@code
sl@0
   217
index of ’c’ in string "abcd" is 2
sl@0
   218
 ’z’ not found in string "abcd"
sl@0
   219
index of ’\0’ in string "abcd" is 4
sl@0
   220
rindex of ’c’ in string "cscab" is 2
sl@0
   221
index of ’\0’ in string "dcab" is 4
sl@0
   222
@endcode
sl@0
   223
@see memchr()
sl@0
   224
@see strchr()
sl@0
   225
@see strcspn()
sl@0
   226
@see strpbrk()
sl@0
   227
@see strsep()
sl@0
   228
@see strspn()
sl@0
   229
@see strstr()
sl@0
   230
@see strtok()
sl@0
   231
sl@0
   232
sl@0
   233
 
sl@0
   234
sl@0
   235
@publishedAll
sl@0
   236
@externallyDefinedApi
sl@0
   237
*/
sl@0
   238
sl@0
   239
/** @fn  rindex(const char *p, int ch)
sl@0
   240
@param p
sl@0
   241
@param ch
sl@0
   242
sl@0
   243
Refer to  index() for the documentation
sl@0
   244
@see memchr()
sl@0
   245
@see strchr()
sl@0
   246
@see strcspn()
sl@0
   247
@see strpbrk()
sl@0
   248
@see strsep()
sl@0
   249
@see strspn()
sl@0
   250
@see strstr()
sl@0
   251
@see strtok()
sl@0
   252
sl@0
   253
sl@0
   254
 
sl@0
   255
sl@0
   256
@publishedAll
sl@0
   257
@externallyDefinedApi
sl@0
   258
*/
sl@0
   259
sl@0
   260
/** @fn  strcasecmp(const char *s1, const char *s2)
sl@0
   261
@param s1
sl@0
   262
@param s2
sl@0
   263
sl@0
   264
Note: This description also covers the following functions -
sl@0
   265
 strncasecmp() 
sl@0
   266
sl@0
   267
@return   The strcasecmp and strncasecmp return an integer greater than, equal to, or less than 0, 
sl@0
   268
according to whether s1 is lexicographically greater than, equal to, or less than s2 after translation of each corresponding character to lower-case. The 
sl@0
   269
strings themselves are not modified.
sl@0
   270
sl@0
   271
  The strcasecmp and strncasecmp functions
sl@0
   272
compare the null-terminated strings s1 and s2. The  strcasecmp() function compares the two strings s1 and s2 , ignoring
sl@0
   273
the case of the characters.
sl@0
   274
sl@0
   275
 The strncasecmp compares at most len characters.
sl@0
   276
sl@0
   277
Examples:
sl@0
   278
@code
sl@0
   279
#include <string.h>
sl@0
   280
#include <stdio.h>
sl@0
   281
int main()
sl@0
   282
{
sl@0
   283
    int ret;
sl@0
   284
    ret = strcasecmp("ABC","abc");
sl@0
   285
    printf("strcasecmp of \"ABC\" \"abc\" is %d
sl@0
   286
",ret);
sl@0
   287
    ret = strcasecmp("abc","abc");
sl@0
   288
    printf("strcasecmp of \"abc\" \"abc\" is %d
sl@0
   289
",ret);
sl@0
   290
    return 0;   
sl@0
   291
}
sl@0
   292
sl@0
   293
@endcode
sl@0
   294
 Output
sl@0
   295
@code
sl@0
   296
strcasecmp of "ABC" "abc" is 0
sl@0
   297
strcasecmp of "abc" "abc" is 0
sl@0
   298
sl@0
   299
@endcode
sl@0
   300
@see bcmp()
sl@0
   301
@see memcmp()
sl@0
   302
@see strcmp()
sl@0
   303
@see strcoll()
sl@0
   304
@see strxfrm()
sl@0
   305
@see tolower()
sl@0
   306
sl@0
   307
sl@0
   308
 
sl@0
   309
sl@0
   310
@publishedAll
sl@0
   311
@externallyDefinedApi
sl@0
   312
*/
sl@0
   313
sl@0
   314
/** @fn  strncasecmp(const char *s1, const char *s2, size_t n)
sl@0
   315
@param s1
sl@0
   316
@param s2
sl@0
   317
@param n
sl@0
   318
sl@0
   319
Refer to  strcasecmp() for the documentation
sl@0
   320
@see bcmp()
sl@0
   321
@see memcmp()
sl@0
   322
@see strcmp()
sl@0
   323
@see strcoll()
sl@0
   324
@see strxfrm()
sl@0
   325
@see tolower()
sl@0
   326
sl@0
   327
sl@0
   328
 
sl@0
   329
sl@0
   330
@publishedAll
sl@0
   331
@externallyDefinedApi
sl@0
   332
*/
sl@0
   333