libclc-developers — Communication between developers of libclc

[Libclc-developers] Copyright notices

[Hallvard B F. <h.b...@us...>]

A lot of libclc files will contain small functions, so I if we put a
huge copyright notice at the top of each, more than half of the released
libclc source text may be copyright notices...

Can we get away with just this notice at the top of files?  That's what
OpenLDAP does.

  Copyright <year> <Author>
  COPYING RESTRICTIONS APPLY, see COPYRIGHT.txt file

-- 
Hallvard

Re: [Libclc-developers] new function: clc_strrev

[Hallvard B F. <h.b...@us...>]

Bj=F8rn Augestad writes:
> We can't have a string module without a strrev function, can we?
> I could not find a proposal for one on google, so here is my version.
> q1: Do we need it?

I don't think so.  I can only remember needing a rev function once or
twice in my life.  I have heroically refrained from posting a few nice
libclc functions I've rarely if ever needed myself:-)

--=20
Hallvard

Re: [Libclc-developers] An alternative clc_list approach + an iterator.

[Hallvard B F. <h.b...@us...>]

Bj=F8rn Augestad writes:
>Hallvard B Furuseth wrote:
>> Iterator: (...)
>>=20
>> Except, we may want more firsts and nexts and whatever, so maybe the
>> iterator functions should start with clc_iter_, not just clc_.
>=20
> clc_first(), clc_last() and friends solves a major issue I've had with=20
> the whole clc_ prefix requirement, it makes the code *look ugly*.=20
> Consider looping over a list:
>     for(s =3D clc_iter_first(i); !clc_iter_atend(i); s =3D clc_iter_next(=
i))
>        ;

      for (s =3D clc_iter_first(i); s; s =3D clc_iter_next(i))
         ;

> Remember that clc_* is *our* global name space and that we are allowed=20
> to place functions there. We just have to be careful when choosing which=
=20
> ones. If the iterator concept is accepted it will be used for most=20
> container adt's and hence be widely used. Widely used stuff should be in
> our global namespace, IMO.

Looks like you are more optimistic for how much iterators will be used
than I am, but I guess it makes sense if you are right.
Maybe I'll re-raise the issue later if the clc_* "global" namespace
gets too full of similar general functions, or if iterators are less
of a success than you hope.

--=20
Hallvard

[Libclc-developers] new function: clc_strrev

[<bo...@me...>]

We can't have a string module without a strrev function, can we?
I could not find a proposal for one on google, so here is my version.
q1: Do we need it?
q2: any bugs?
q3: other comments?

Enjoy.
Bjørn


/* $id$
  * Copyright(c) 2003, B. Augestad (bo...@me...)
  */

/* documentation start:
SYNOPSIS
     #include <clc_string.h>
     char* clc_strrev(char* s);

DESCRIPTION
     clc_strrev() - reverses the contents of a string.

PARAMETERS
     s - The string to reverse

RETURN VALUE
     Returns the parameter s

ERROR HANDLING
     The release version of libclc performs no error checking. The debug
     version asserts that s isn't a NULL pointer.

EXAMPLE
     char buf[100];
     strcpy(buf, "Hello, World");
     clc_strrev(buf);
     printf("%s\n", buf);

AUTHOR
     B. Augestad, bo...@me...

BUGS
     None known

  * documentation end:
  */

#include <string.h>

#include "clc_assert.h"
#include "clc_string.h"

char* clc_strrev(char* s)
{
     size_t left, right, middle, cb;

     clc_assert_not_null(clc_strrev, s);

     cb = strlen(s);
     middle = cb / 2;
     for(left = 0; left < middle; left++) {
         char tmp;

         right = cb - left - 1;
         tmp = s[left];
         s[left] = s[right];
         s[right] = tmp;
     }

     return s;
}

#ifdef CLC_TEST
int main(void)
{
     char odd[100], even[100], empty[100];

     strcpy(odd, "12345");
     strcpy(even, "123456");
     strcpy(empty, "");

     printf("odd  :%s\n", clc_strrev(odd));
     printf("even :%s\n", clc_strrev(even));
     printf("empty:%s\n", clc_strrev(empty));

     return 0;
}
#endif

[Libclc-developers] String functions so far (2)

[Hallvard B F. <h.b...@us...>]

I've updated the documentation for clc_string.h a bit.
Comments welcome.

The source code for the functions can be viewed at
<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/libclc/libclc/src/string/>.

Changes since first posting (only changed wording, not functionality):
- Merged some manpages, reducing the text by 15%.
- Changed #include "clc_string.h" to <clc_string.h> in SYNOPSISes.
- Changed "compare bytes" to "compare characters" in str{n}casecmp().
- Added a NOTE about (char*)0 vs. NULL for clc_stralloc().
- Fixed examples: strfoo() -> clc_strfoo(), and some other stuff.
- Added some clc_* functions to SEE ALSO, and clc(3) which ought to be
  written:-)
- Added AUTHOR Howard Chu for clc_strendcpy and Dan Pop for clc_strdup.


clc_string.h:

#ifndef CLC_STRING_H
#define CLC_STRING_H

#include <stddef.h>
#include "clc_settings.h"

#ifdef __cplusplus
extern "C" {
#endif

char* clc_strdup(const char* CLC_RESTRICT clc_s);

char* clc_strtrim(char* clc_s);
char* clc_strrtrim(char* clc_s);
char* clc_strltrim(char* clc_s);
char* clc_strlwr(char *clc_s);
char* clc_strnorm(char *clc_s);
char* clc_strupr(char *clc_s);

char* clc_stralloc(const char *clc_arg1, ...);
char* clc_stpcpy(
        char* CLC_RESTRICT clc_s1,
        const char* CLC_RESTRICT clc_s2);

char* clc_strendcpy(
        char* clc_dest,
        const char* CLC_RESTRICT clc_src,
        const char* clc_end);

int clc_ultostr(
        char* clc_ptr,
        size_t clc_size,
        unsigned long clc_num,
        int clc_base);

size_t clc_strlcpy(
        char* CLC_RESTRICT clc_dest,
        const char* CLC_RESTRICT clc_src,
        size_t clc_size);

size_t clc_strlcat(
        char* CLC_RESTRICT clc_dest,
        const char* CLC_RESTRICT clc_src,
        size_t clc_size);

char* clc_strsep(
        char** CLC_RESTRICT clc_stringp,
        const char* CLC_RESTRICT clc_delim);

char* clc_strtok_r(
        char* clc_str,
        const char* CLC_RESTRICT clc_delim,
        char** clc_tracker);

#ifdef __cplusplus
}
#endif

#endif /* CLC_STRING_H */



NAME
    clc_stpcpy - copy string and return pointer to end

SYNOPSIS
    #include <clc_string.h>
    char *clc_stpcpy(char *CLC_RESTRICT s1,
                     const char *CLC_RESTRICT s2);

    Link with: clc library.

DESCRIPTION
    This function copies string s2 to s1.

RETURN VALUE
    clc_stpcpy() returns a pointer to the terminating null character in
    s1.

EXAMPLE
    clc_stpcpy(clc_stpcpy(buffer, basename), ".txt");

SEE ALSO
    clc(3), strcpy(3), clc_strendcpy(3)



NAME
    clc_strendcpy - copy limited string and return pointer to end

SYNOPSIS
    #include <clc_string.h>
    char *clc_strendcpy(char *dst, const char *CLC_RESTRICT src,
                        const char *end);

    Link with: clc library.

DESCRIPTION
    clc_strendcpy() copies the string src to dst, truncates it if
    the length is >= end, and null-terminates it.
    Nothing is done if dst >= end.

RETURN VALUE
    clc_strendcpy() returns a pointer to the terminating null character
    in dst, or to end (i.e. one past the null) if the string was
    truncated.  It return dst if end >= dst.

EXAMPLE
    char buf[80], *end = buf + sizeof(buf);
    char *dst = clc_strendcpy(buf, str1, end);
    dst = clc_strendcpy(dst, str2, end);
    if (dst >= end)
        warning("string was truncated");

SEE ALSO
    clc(3), strcpy(3), strncpy(3), clc_strlcpy(3), clc_stpcpy(3)

AUTHOR
    Howard Chu



NAME
    clc_strlcat, clc_strlcpy - safe string copy and concatenation

SYNOPSIS
    #include <clc_string.h>
    size_t clc_strlcpy(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);
    size_t clc_strlcat(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);

    Link with: clc library.

DESCRIPTION
    clc_strlcpy() copies the string src to dest.  It copies at most
    size-1 characters, and if size != 0 it then null-terminates dest.

    clc_strlcat() appends the string src to dest.  It appends at most
    size-1-strlen(dest) characters, and if size != 0 it then null-
    terminates dest.  Dest is not truncated if size <= strlen(dest).

    You can check for truncation by checking if the return values
    are less than size, except when clc_strlcat() is given a dest
    string which is >= size.

RETURN VALUES
    clc_strlcpy() returns strlen(src).
    clc_strlcat() returns strlen(dest) + strlen(src).

EXAMPLE
    if (clc_strlcat(buf, "text", sizeof(buf)) >= sizeof(buf))
        printf(stderr, "Value was truncated.\n");

ACKNOWLEDGMENTS
    These functions were invented by Todd C. Miller and Theo de Raadt,
    see <http://www.courtesan.com/todd/papers/strlcpy.html>.

SEE ALSO
    clc(3), clc_strendcpy(3), clc_stpcpy(3), strncpy(3), strncat(3)



NAME
    clc_strdup - allocate a duplicate of a string

SYNOPSIS
    #include <clc_string.h>
    char *clc_strdup(const char * CLC_RESTRICT s);

    Link with: clc library.

DESCRIPTION
    clc_strdup() creates a malloced copy of the string s.
    The result should be freed with free().

RETURN VALUE
    The function returns the duplicated string, or NULL if enough space
    could not be allocated.

EXAMPLE
    char *s = clc_strdup("foo");
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc(3), clc_stralloc(3), malloc(3), free(3), strcpy(3)

AUTHOR
    Dan Pop



NAME
    clc_stralloc - allocate a concatenation of strings

SYNOPSIS
    #include <clc_string.h>
    char *clc_stralloc(const char *arg1, ...);

    Link with: clc library.

DESCRIPTION
    This function takes zero or more string arguments followed by
    (char*)0, and concatenates them.
    The result should be freed with free().

RETURN VALUE
    clc_stralloc() returns a malloced concatenation of the arguments,
    or NULL if enough space could not be allocated.

NOTE
    Use (char*)0, not NULL, to end the list of parameters.  The two may
    have different representations in a list of variable arguments.

EXAMPLE
    char *s = clc_stralloc("foo", "bar", (char *)0);
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc(3), clc_strdup(3), malloc(3), free(3), strcpy(3)



NAME
    clc_strsep, clc_strtok_r - extract token from string

SYNOPSIS
    #include <clc_string.h>
    char *clc_strsep(char **CLC_RESTRICT stringp,
                     const char *CLC_RESTRICT delim);
    char *clc_strtok_r(char *str, const char *CLC_RESTRICT delim,
                       char **tracker);

    Link with: clc library.

DESCRIPTION
    These functions split a string up in tokens delimited by any
    character in the delim parameter, like strtok() does.  Each token
    starts with the first character in the input string which is does
    not occur in delim, and ends with the next character which occurs in
    delim or with the terminating null character.

    The functions put a null character after the token in the input
    string.

    clc_strsep() takes *stringp as the input string.  It updates
    *stringp to point just past the null character in the returned
    token, or possibly to a null character when returning the last
    token.

    clc_strtok_r() takes the input string as the str parameter at the
    first call, and NULL at subsequent calls which split the same
    string.  The caller must supply a char* variable to the tracker
    parameter, the same variable for each call while splitting a string.
    This is used internally by clc_strtok_r to keep track of its
    position in the string being broken up.

    The advantages of these functions over strtok is that you need not
    split just one string at a time, and that they are thread-safe.

RETURN VALUES
    The functions return a pointer to the next token in the supplied
    string, or NULL if there are no more tokens.

EXAMPLES
    char buffer[80], *token, *s, *tracker;
    ...
    for (s = buffer; token = clc_strsep(&s, " \t"); )
        puts(token);
    ...
    s = buffer;
    while ((token = clc_strtok_r(s, " \t", &tracker)) != NULL)) {
        puts(token);
        s = NULL;
    }

SEE ALSO
    clc(3), strtok(3)



NAME
    clc_strcasecmp, clc_strncasecmp - case-insensitive string compare

SYNOPSIS
    #include <clc_string.h>
    char *clc_strcasecmp(const char *s1, const char *s2);
    char *clc_strncasecmp(const char *s1, const char *s2, size_t len);

    Link with: clc library.

DESCRIPTION
    These functions compare two strings character by character, ignoring
    differences in case.
    clc_strcasecmp() compares up to the first null character.
    clc_strncasecmp() compares up to the first null character or until
    the length parameter len is reached.

RETURN VALUE
    The functions return 0 if the strings compare equal, a negative
    value if s1 is less by unsigned char comparison, and a positive
    value if s2 is less.

EXAMPLE
    if(clc_strcasecmp(name, "Augestad") == 0)
        puts("Pedantic C freak.");

SEE ALSO
    clc(3), strcmp(3), strncmp(3)



NAME
    clc_strtrim, clc_strltrim, clc_strrtrim, clc_strnorm
    - trim whitespace from string

SYNOPSIS
    #include <clc_string.h>
    char *clc_strtrim(char *s);
    char *clc_strltrim(char *s);
    char *clc_strrtrim(char *s);
    char *clc_strnorm(char *s);

    Link with: clc library.

DESCRIPTION
    These functions modify the input string.
    clc_strtrim() removes whitespace surrounding the string.
    clc_strltrim() removes whitespace at the beginning of the string.
    clc_strrtrim() removes whitespace at the end of the string.
    clc_strnorm() removes whitespace surrounding the string, and
    converts all remaining groups of whitespace to a single space.

RETURN VALUES
    The functions return the s parameter with the modified string.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        puts(clc_strnorm(buffer));

SEE ALSO
    clc(3), isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strlwr, clc_strupr - convert string in place to lower/uppercase

SYNOPSIS
    #include <clc_string.h>
    char *clc_strlwr(char *s);
    char *clc_strupr(char *s);

    Link with: clc library.

DESCRIPTION
    These functions modify the input string.
    clc_strlwr() converts the input string to lowercase.
    clc_strupr() converts the input string to uppercase.

RETURN VALUE
    The functions return the s parameter with the modified string.

SEE ALSO
    clc(3), tolower(3), toupper(3)

AUTHOR
    Eric G. Miller



-- 
Hallvard

Re: [Libclc-developers] Re: clc_ultostr(5)

[<bo...@me...>]

Jan Engelhardt wrote:
> 
> Other thing: when you said comp.lang.c shall approve functions,
> I recall that they claimed about the topicality of libclc in there...
> i think this list is fine for it.
Not quite sure if I understand you 100%, but if I do...

I followed the topicality thread and I think that we should keep project 
related stuff out of c.l.c. Discussion of code, interfaces and design is 
OK to discuss in c.l.c. That seemed to be the majority opinion in the 
group.

This list is great for many purposes, and much better than c.l.c to 
discuss things, but c.l.c must make the final decision on
- what goes into the library
- the semantics of functions
- the implementation of functions

Some may see that as a limitation, to me it is our greatest advantage. 
Progress isn't the best doing it this way, but the quality is 
unbelieveable. :-)

Bjørn

[Libclc-developers] Re: clc_ultostr(5)

[Jan E. <je...@li...>]

>I found a few more bugs in this function. Below is a copy of the latest
>CVS version. Lesson learned: No more submissions without a test program? ;-)

I was too lazy to download libclc for this machine ;)

>int clc_ultostr(char *ptr, size_t size, unsigned long num, int base)
>{
>     const char *sym = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
>     char* sp;

Hey your style ain't even consistent (char* and char *)

>     /* Point to the last char in buffer */
Prefering //

I once addressed that sp was startp, but that seems to be overlooked,
anyway it's fixed . in here.

>     sp = ptr + size - 1;
>     *sp = '\0';
>     do {
>         *--sp = sym[num % base];
>         num /= base;
>     } while (num > 0 && sp != ptr);
>
>     if(num > 0)
>         return 0;
>     else if(ptr != sp)
>         memmove(ptr, sp, size - (sp - ptr));

Other thing: when you said comp.lang.c shall approve functions,
I recall that they claimed about the topicality of libclc in there...
i think this list is fine for it.


- Jan Engelhardt

[Libclc-developers] clc_ultostr(5)

[<bo...@me...>]

I found a few more bugs in this function. Below is a copy of the latest 
CVS version. Lesson learned: No more submissions without a test program? ;-)

#include <stddef.h>
#include <string.h>

#include "clc_assert.h"
#include "clc_string.h"

/* Copyright(c) 2003, Jan Engelhart (hir...@us...) */

/* Comments from boa:
  * The previous version was broken in several ways.
  * 1. We must place the result from ptr[0] and rightwards.
  *    If we don't and ptr[0] == '\0', nothing is printed.
  *    memmove fixes that.
  *
  * 2. The previous version wrote outside the buffer, I added (size - 1).
  */
int clc_ultostr(char *ptr, size_t size, unsigned long num, int base)
{
     const char *sym = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
     char* sp;

     clc_assert_not_null(clc_ultostr, ptr);
     clc_assert_arg(clc_ultostr, size > 1);
     clc_assert_arg(clc_ultostr, base >= 2 && base <= 36);

     /* Point to the last char in buffer */
     sp = ptr + size - 1;
     *sp = '\0';
     do {
         *--sp = sym[num % base];
         num /= base;
     } while (num > 0 && sp != ptr);

     if(num > 0)
         return 0;
     else if(ptr != sp)
         memmove(ptr, sp, size - (sp - ptr));

     return 1;
}

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

Re: [Libclc-developers] An alternative clc_list approach + an iterator.

[<bo...@me...>]

Hallvard B Furuseth wrote:
> Iterator:
> 
> clc_begin() and clc_end() looks like functions that begin and end
> something.  Call them clc_atstart() and clc_atend().

Not a bad idea. ;-)

> 
> Except, we may want more firsts and nexts and whatever, so maybe the
> iterator functions should start with clc_iter_, not just clc_.


clc_first(), clc_last() and friends solves a major issue I've had with 
the whole clc_ prefix requirement, it makes the code *look ugly*. 
Consider looping over a list:
    for(s = clc_iter_first(i); !clc_iter_atend(i); s = clc_iter_next(i))
       ;

It's way too verbose and people will go blind trying to find out what 
the line does. Even with the shortest possible variable names (s&i) and 
a single indentation level of 4 spaces, a line will be 72 characters 
wide!  Now use 8 chars for indentation and add an indentation level or 
two. :-(

I will have a very hard time living with code like that. This is much 
more acceptable:
    for(s = clc_first(i); !clc_atend(i); s = clc_next(i))
       ;

Remember that clc_* is *our* global name space and that we are allowed 
to place functions there. We just have to be careful when choosing which 
ones. If the iterator concept is accepted it will be used for most 
container adt's and hence be widely used. Widely used stuff should be in 
our global namespace, IMO.

(BTW, I would not have named clc_first()/clc_last() just first()/last() 
if there wasn't a prefix requirement.)

Other opinions?


-- 
boa

Re: [Libclc-developers] String functions so far

[<bo...@me...>]

Hallvard B Furuseth wrote:
> Here are clc_string.h and the documentation of the functions,
> except clc_ultostr.  Please comment.

Very nice work, Hallvard!

This should be the standard for libclc and be an example to all of us. 
Thanks.

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

Re: [Libclc-developers] An alternative clc_list approach + an iterator.

[<bo...@me...>]

Hallvard B Furuseth wrote:
> Iterator:
> 
> clc_begin() and clc_end() looks like functions that begin and end
> something.  Call them clc_atstart() and clc_atend().
> 
> Except, we may want more firsts and nexts and whatever, so maybe the
> iterator functions should start with clc_iter_, not just clc_.
> 
> List:
> 
> I still think the names should either be _new and _delete like in C++
> or _alloc and _free like in C.  Not the mix _new and _free.
> Or neither: _make and _destroy, or something.
> 

I see your point and have seen it all along. It's just that I have one 
more adt up my sleeve which I haven't mentioned at all. This may be the 
time?

The adt is a a general purpose pool. It can be used as e.g. a resource 
pool, where the "resource" is an adt. The pool e.g. can be a pool of 
preallocated clc_list objects. This concept is IMO a very good idea in 
some applications, e.g. high performance multithreaded servers where you 
want to avoid malloc()/free() bottlenecks or if you want to utilize 
available memory better by allocating larger chucks of memory and then 
subdivide it into fixed sizes.

The naming problem arises *if* we allow for custom allocators in 
conjunction with our adt's. Straight malloc/free creation can be named 
alloc/free, using a pool better names could be get/release. I currently 
have no good solution, and that's why I've dodged the issue.

Now you all know my dark secret :-)
-- 
boa

Re: [Libclc-developers] An alternative clc_list approach + an iterator.

[Hallvard B F. <h.b...@us...>]

Iterator:

clc_begin() and clc_end() looks like functions that begin and end
something.  Call them clc_atstart() and clc_atend().

Except, we may want more firsts and nexts and whatever, so maybe the
iterator functions should start with clc_iter_, not just clc_.

List:

I still think the names should either be _new and _delete like in C++
or _alloc and _free like in C.  Not the mix _new and _free.
Or neither: _make and _destroy, or something.

-- 
Hallvard

Re: [Libclc-developers] String functions so far

[Hallvard B F. <h.b...@us...>]

Hallvard B Furuseth writes:

>     clc_strendcpy() returns a pointer to the terminating null character
>     in dst, or to end (i.e. one past the null) if the string was
>     truncated.  It return dst if end >= dst.

Would it be better to return end if end >= dst?  Then one could
check for truncation with 'ret == end' instead of 'ret >= end',
which is slightly nicer.

Are there any disadvantages with returning end in this case?

>     clc_strnorm - remove duplicate/surrounding whitespace from string

I thought we were to rename this function to something else?
Chuck suggested clc_compactws(), David clc_normws().  My vote
is for clc_compactws, unless someone has a better name.

>     clc_strlwr - convert string in place to lowercase
>     clc_strupr - convert string in place to uppercase

clc_strlower and clc_strupper is easier to read, and still short enough.
But I think these were deliberately made short in a comp.lang.c thread,
so maybe that discussion belongs on comp.lang.c.

-- 
Hallvard

Re: [Libclc-developers] clc_string module

[Bryan D. <bd...@bd...>]

=2D----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Saturday 22 March 2003 03:44 am, Bj=F8rn Augestad wrote:
> Here are the functions currently present with source code:
>
>    char* clc_strdup(const char* CLC_RESTRICT clc_s);
>    char* clc_strtrim(char* clc_s);
>    char* clc_strrtrim(char* clc_s);
>    char* clc_strltrim(char* clc_s);
>    char* clc_strlwr(char *clc_s);
>    char* clc_strnorm(char *clc_s);
>    char* clc_strupr(char *clc_s);
>    char* clc_stralloc(const char *arg1, ...);
>    int clc_ultostr(char *ptr, size_t size, unsigned long num, int base);
>
> The observant reader may notice that not all proposed functions are
> present. If anyone has the source code (and documentation?) for one or
> more of them, please post it on this mailing list or email them to Randy
> or myself. clc_stpcpy() is very much in demand as clc_stralloc() won't
> link without it.

What does it do, again?
=2D----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)

iD8DBQE+fHHCx533NjVSos4RAltnAJ4m5s5uYpfn8DqfrLAMJ8gSkXHmGQCdEGSw
mZvZ7arIZaJAxcOrAW/HCcw=3D
=3DMg9E
=2D----END PGP SIGNATURE-----

[Libclc-developers] An alternative clc_list approach + an iterator.

[<bo...@me...>]

Attached is a file containing a list adt as well as an iterator adt. It 
even contains a readme, a test program and a Makefile.

The list adt, clc_list, is a traditional list. The interface it 
currently not complete as this version is just a proof of concept.

The iterator is capable of iterating on any data structure, provided 
that it is initialized properly. It should therefore be possible to use 
it for many different things in libclc, including maps, sets and hashes.

Please review and comment. I think that most errors, conceptual and 
others, must be removed before the concept is presented to c.l.c, so 
this review may turn out to be very important.

Thanks in advance.
Bjørn

[Libclc-developers] String functions so far

[Hallvard B F. <h.b...@us...>]

Here are clc_string.h and the documentation of the functions,
except clc_ultostr.  Please comment.

I've included the suggested documentation for clc_str{n}casecmp, but not
included them in clc_string.h since there has been no discussion about
them.



#ifndef CLC_STRING_H
#define CLC_STRING_H

#include <stddef.h>
#include "clc_settings.h"

#ifdef __cplusplus
extern "C" {
#endif

char* clc_strdup(const char* CLC_RESTRICT clc_s);

char* clc_strtrim(char* clc_s);
char* clc_strrtrim(char* clc_s);
char* clc_strltrim(char* clc_s);
char* clc_strlwr(char *clc_s);
char* clc_strnorm(char *clc_s);
char* clc_strupr(char *clc_s);

char* clc_stralloc(const char *clc_arg1, ...);
char* clc_stpcpy(
	char* CLC_RESTRICT clc_s1,
	const char* CLC_RESTRICT clc_s2);

char* clc_strendcpy(
	char* clc_dest,
	const char* CLC_RESTRICT clc_src,
	const char* clc_end);

int clc_ultostr(
	char* clc_ptr,
	size_t clc_size,
	unsigned long clc_num,
	int clc_base);

size_t clc_strlcpy(
	char* CLC_RESTRICT clc_dest,
	const char* CLC_RESTRICT clc_src,
	size_t clc_size);

size_t clc_strlcat(
	char* CLC_RESTRICT clc_dest,
	const char* CLC_RESTRICT clc_src,
	size_t clc_size);

char* clc_strsep(
	char** CLC_RESTRICT clc_stringp,
	const char* CLC_RESTRICT clc_delim);

char* clc_strtok_r(
	char* clc_str,
	const char* CLC_RESTRICT clc_delim,
	char** clc_tracker);

#ifdef __cplusplus
}
#endif

#endif /* CLC_STRING_H */





NAME
    clc_stpcpy - copy string and return pointer to end

SYNOPSIS
    #include "clc_string.h"
    char *clc_stpcpy(char *CLC_RESTRICT s1,
                     const char *CLC_RESTRICT s2);

    Link with: clc library.

DESCRIPTION
    This function copies string s2 to s1.

RETURN VALUE
    clc_stpcpy() returns a pointer to the terminating null character in
    s1.

EXAMPLE
    clc_stpcpy(clc_stpcpy(buffer, basename), ".txt");

SEE ALSO
    strcpy(3)



NAME
    clc_strendcpy - copy limited string and return pointer to end

SYNOPSIS
    #include "clc_string.h"
    char *clc_strendcpy(char *dst, const char *CLC_RESTRICT src,
                        const char *end);

    Link with: clc library.

DESCRIPTION
    clc_strendcpy() copies the string src to dst, truncates it if
    the length is >= end, and null-terminates it.
    Nothing is done if dst >= end.

RETURN VALUE
    clc_strendcpy() returns a pointer to the terminating null character
    in dst, or to end (i.e. one past the null) if the string was
    truncated.  It return dst if end >= dst.

EXAMPLE
    char buf[80], *end = buf + sizeof(buf);
    char *dst = strendcpy(strendcpy(buf, str1, end), str2, end);
    if (dst >= end)
        warning("string was truncated");

SEE ALSO
    strcpy(3), strncpy(3), clc_strlcpy(3)



NAME
    clc_strlcat, clc_strlcpy - safe string copy and concatenation

SYNOPSIS
    #include "clc_string.h"
    size_t clc_strlcpy(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);
    size_t clc_strlcat(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);

    Link with: clc library.

DESCRIPTION
    clc_strlcpy() copies the string src to dest.  It copies at most
    size-1 characters, and if size != 0 it then null-terminates dest.

    clc_strlcat() appends the string src to dest.  It appends at most
    size-1-strlen(dest) characters, and if size != 0 it then null-
    terminates dest.  Dest is not truncated if size <= strlen(dest).

    You can check for truncation by checking if the return values
    are less than size, except when clc_strlcat() is given a dest
    string which is >= size.

RETURN VALUES
    clc_strlcpy() returns strlen(src).
    clc_strlcat() returns strlen(dest) + strlen(src).

EXAMPLE
    if (clc_strlcat(buf, "text", sizeof(buf)) >= sizeof(buf))
        printf(stderr, "Value was truncated.\n");

ACKNOWLEDGMENTS
    These functions were invented by Todd C. Miller and Theo de Raadt,
    see <http://www.courtesan.com/todd/papers/strlcpy.html>.

SEE ALSO
    clc_strendcpy(3), strncpy(3), strncat(3)



NAME
    clc_strdup - allocate a duplicate of a string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strdup(const char * CLC_RESTRICT s);

    Link with: clc library.

DESCRIPTION
    clc_strdup() creates a malloced copy of the string s.
    The result should be freed with free().

RETURN VALUE
    The function returns the duplicated string, or NULL if enough space
    could not be allocated.

EXAMPLE
    char *s = clc_strdup("foo");
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc_stralloc(3), malloc(3), strcpy(3)



NAME
    clc_stralloc - allocate a concatenation of strings

SYNOPSIS
    #include "clc_string.h"
    char *clc_stralloc(const char *arg1, ...);

    Link with: clc library.

DESCRIPTION
    This function takes zero or more string arguments followed by
    (char*)0, and concatenates them.
    The result should be freed with free().

RETURN VALUE
    clc_stralloc() returns a malloced concatenation of the arguments,
    or NULL if enough space could not be allocated.

EXAMPLE
    char *s = clc_stralloc("foo", "bar", (char *)0);
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc_strdup(3), malloc(3), strcpy(3)



NAME
    clc_strsep, clc_strtok_r - extract token from string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strsep(char **CLC_RESTRICT stringp,
                     const char *CLC_RESTRICT delim);
    char *clc_strtok_r(char *str, const char *CLC_RESTRICT delim,
                       char **tracker);

    Link with: clc library.

DESCRIPTION
    These functions split a string up in tokens delimited by any
    character in the delim parameter, like strtok() does.  Each token
    starts with the first character in the input string which is does
    not occur in delim, and ends with the next character which occurs in
    delim or with the terminating null character.

    The functions put a null character after the token in the input
    string.

    clc_strsep() takes *stringp as the input string.  It updates
    *stringp to point just past the null character in the returned
    token, or possibly to a null character when returning the last
    token.

    clc_strtok_r() takes the input string as the str parameter at the
    first call, and NULL at subsequent calls which split the same
    string.  The caller must supply a char* variable to the tracker
    parameter, the same variable for each call while splitting a string.
    This is used internally by clc_strtok_r to keep track of its
    position in the string being broken up.

    The advantages of these functions over strtok is that you need not
    split just one string at a time, and that they are thread-safe.

RETURN VALUES
    The functions return a pointer to the next token in the supplied
    string, or NULL if there are no more tokens.

EXAMPLES
    char buffer[80], *token, *s, *tracker;
    ...
    for (s = buffer; token = strsep(&s, " \t"); )
        puts(token);
    ...
    for (s = buffer; token = clc_strtok_r(s, " \t", &tracker); s = NULL)
        puts(token);

SEE ALSO
    strtok(3)



NAME
    clc_strcasecmp - case-insensitive string compare

SYNOPSIS
    #include "clc_string.h"
    char *clc_strcasecmp(const char *s1, const char *s2);

    Link with: clc library.

DESCRIPTION
    This function compares two strings byte by byte, ignoring
    differences in case.

RETURN VALUE
    The function returns 0 if the strings compare equal, a negative
    value if s1 is less by unsigned char comparison, and a positive
    value if s2 is less.

EXAMPLE
    if(strcasecmp(name, "Augestad") == 0)
        puts("Great person.");

SEE ALSO
    strcmp(3), clc_strncasecmp(3)




NAME
    clc_strncasecmp - case-insensitive string compare with size limit

SYNOPSIS
    #include "clc_string.h"
    char *clc_strncasecmp(const char *s1, const char *s2, size_t len);

    Link with: clc library.

DESCRIPTION
    This function compares two strings byte by byte, ignoring
    differences in case, up to the first null character or until
    the length parameter len is reached.

RETURN VALUE
    The function returns 0 if the strings compare equal, a negative
    value if s1 is less by unsigned char comparison, and a positive
    value if s2 is less.

EXAMPLE
    if(strncasecmp(buffer, arg, sizeof(buffer)) == 0)
        puts("The argument starts with the proper string.");

SEE ALSO
    strncmp(3), clc_strcasecmp(3)



NAME
    clc_strltrim - trim whitespace from the left of string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strltrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        puts(clc_strltrim(buffer));

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strrtrim - trim whitespace at the right of string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strrtrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the end of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    *buffer = '\0';
    if (fgets(buffer, sizeof(buffer), f))
        clc_strrtrim(buffer);
    return buffer;

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strtrim - trim whitespace surrounding string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strtrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning and end of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        return clc_strtrim(buffer);
    return NULL;

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strnorm - remove duplicate/surrounding whitespace from string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strnorm(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning and end of the string, and converting all remaining
    groups of whitespace to a single space.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        puts(clc_strnorm(buffer));

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strlwr - convert string in place to lowercase

SYNOPSIS
    #include "clc_string.h"
    char *clc_strlwr(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by converting it to
    lowercase.

RETURN VALUE
    The function returns the s parameter.

SEE ALSO
    tolower(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strupr - convert string in place to uppercase

SYNOPSIS
    #include "clc_string.h"
    char *clc_strupr(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by converting it to
    uppercase.

RETURN VALUE
    The function returns the s parameter.

SEE ALSO
    toupper(3)

AUTHOR
    Eric G. Miller



-- 
Hallvard

Re: [Libclc-developers] clc_string module

[Bryan D. <bd...@bd...>]

=2D----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Saturday 22 March 2003 09:31 am, Bj=F8rn Augestad wrote:
> Bryan Donlan wrote:
> >>or myself. clc_stpcpy() is very much in demand as clc_stralloc() won't
> >>link without it.
> >
> > What does it do, again?
>
> Good question. I didn't remember either. :-)
>
> It really doesn't matter anymore as Hallvard has added it already. He's
> even writing documentation!

Oh, I see. It returns the null terminator. nm.
=2D----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)

iD8DBQE+fHSox533NjVSos4RAnNRAJ4zXPh2lSaMS8+oLldg/fwar5OJRACdHm1x
UyDle6IUTh89QHCFRQoevJk=3D
=3DtXmt
=2D----END PGP SIGNATURE-----

Re: [Libclc-developers] clc_string module

[<bo...@me...>]

Bryan Donlan wrote:
>>or myself. clc_stpcpy() is very much in demand as clc_stralloc() won't
>>link without it.
> 
> 
> What does it do, again?

Good question. I didn't remember either. :-)

It really doesn't matter anymore as Hallvard has added it already. He's 
even writing documentation!

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

[Libclc-developers] strings: clc_str{n}casecmp()

[Hallvard B F. <h.b...@us...>]

Shall I add clc_strcasecmp() and clc_strncasecmp()
to the clc string library?  They do the same as strcmp/strncmp,
except they are case-insensitive.

-- 
Hallvard

Re: [Libclc-developers] clc_string module

[Michael B.A. <mb...@io...>]

On Sat, 22 Mar 2003 11:17:20 +0100
Bj=F8rn Augestad <bo...@me...> wrote:

> Michael B.Allen wrote:
> >>- Check out the prototypes at the top of this post. IMO clc_ultostr()=20
> >>should return char* instead of int.
> >=20
> >=20
> > But then you can't do stuff this:
> >=20
> > for (i =3D 0; i < 100; i++) {
> > 	if ((n =3D clc_ultostr(dst, dn, vals[i], 16)) =3D=3D -1) {
> > 		return -1; /* ran out of space */
> > 	}
> > 	dst +=3D n; dn -=3D n;
> > 	*dst++ =3D ','; dn--;
> > }
> >=20
> > This is why the printfs return the amount of memory consumed. This is
> > important to "recursive composition".
> >=20
> > Mike
> >=20
>=20
> That is a solvable problem. :-)
> One possible solution is to add a call to strlen().
>=20
> for (i =3D 0; i < 100; i++) {
> 	if( (s =3D clc_ultostr(dst, dn, vals[i], 16)) =3D=3D NULL) {
> 		return -1; /* ran out of space */
> 	}
>=20
> 	n =3D strlen(s);
> 	dst +=3D n; dn -=3D n;
> 	*dst++ =3D ','; dn--;
> }
>=20
> FWIW, here are my contradicting opinions.
> 1) It's a good idea to have a coherent interface if possible

Coherent with what? If the clc_ultostr is like sprintf then it should
return int yes?

> 2) Interfaces allowing fast code is better than the alternative slow code.

I don't understand. What you are suggesting is slower.

Mike

--=20
A  program should be written to model the concepts of the task it
performs rather than the physical world or a process because this
maximizes  the  potential  for it to be applied to tasks that are
conceptually  similar and, more important, to tasks that have not
yet been conceived.=20

Re: [Libclc-developers] clc_string module

[<bo...@me...>]

Michael B.Allen wrote:
>>- Check out the prototypes at the top of this post. IMO clc_ultostr() 
>>should return char* instead of int.
> 
> 
> But then you can't do stuff this:
> 
> for (i = 0; i < 100; i++) {
> 	if ((n = clc_ultostr(dst, dn, vals[i], 16)) == -1) {
> 		return -1; /* ran out of space */
> 	}
> 	dst += n; dn -= n;
> 	*dst++ = ','; dn--;
> }
> 
> This is why the printfs return the amount of memory consumed. This is
> important to "recursive composition".
> 
> Mike
> 

That is a solvable problem. :-)
One possible solution is to add a call to strlen().

for (i = 0; i < 100; i++) {
	if( (s = clc_ultostr(dst, dn, vals[i], 16)) == NULL) {
		return -1; /* ran out of space */
	}

	n = strlen(s);
	dst += n; dn -= n;
	*dst++ = ','; dn--;
}

FWIW, here are my contradicting opinions.
1) It's a good idea to have a coherent interface if possible
2) Interfaces allowing fast code is better than the alternative slow code.

I'm sure that c.l.c can provide even more opinions :-)

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

Re: [Libclc-developers] CLC_VERSION (Was: clc_string module)

[Hallvard B F. <h.b...@us...>]

Bj=F8rn Augestad writes:
>>     #define CLC_VERSION_MAJOR    0
>>     #define CLC_VERSION_MINOR    1
>>     #define CLC_VERSION_REVISION 3
>>     #define CLC_VERSION (1000000L * CLC_VERSION_MAJOR \
>> 			 +  1000L * CLC_VERSION_MINOR \
>> 			 + CLC_VERSION_REVISION)
>> and code like
>> #if CLC_VERSION < 1003005 / whatever / #else / something / #endif
>=20
> #define'ing the version numbers makes it harder to keep version numbers=20
> and file names in sync. Since we sooner or later will start tagging the=20
> files in CVS, we have yet another possibility for version number errors.
>=20
> If we end up using autoconf, then a version is available at compile time=
=20
> already (Unfortunately as a quoted string). Maybe some autoconf+m4 magic=
=20
> can create what we need automatically?

Contributors don't say 'version 1.2.3' in the documentation they supply
with the change.  They say '@CLC_VERSION@' or something.

Before a release, you replace all @CLC_VERSION@s in the documentation
with 'clc version 1.2.3' or whatever, and you update the CLC_VERSION_*
macros above in clc.h.  Both can be done by a script.  I'll supply it
if you wish, as soon as we agree on the details above.

--=20
Hallvard

Re: [Libclc-developers] CLC_VERSION (Was: clc_string module)

[<bo...@me...>]

Hallvard B Furuseth wrote:
> Bjørn Augestad writes:
> 
>>- I have released libclc 0.1.3 for download. This version contains the 
>>new string functions.
> 
> 
> Do we need 3 levels of versions?


> 
> The more dots in the version, the more dots in the library filename if
> one wants multiple versions in the filesystem.  I'd prefer just a major
> and a minor version, that's easier to maintain.  Major version for API
> changes, minor version for API updates, additions, bugfixes, and
> generally if the minor version gets too large.

The current numbering scheme is copied from Linux, which I find quite 
good. We currently use x.y.z where x is major release number, y is 
minor, where odd numbers are developer versions and even numbers are 
release versions. z is used for bug fixes and patches. Not that we need 
bug fixes... :-)

My current hope is that we can release libclc-0.2 with the string module 
in April. Then I hope to release 0.4 in June, including a clc_list and a 
general purpose iterator.

We therefore need 0.2.z to handle patches needed for release 0.2, as we 
will use 0.3.z to release developer versions of the upcoming 0.4 version.

> 
> BTW, this brings up a point I have been thinking about:
> 
> I think that after libclc version 1, most changes to libclc should be
> noted in HISTORY sections of the relevant functions' documentation, and
> clc.h should contain a CLC_VERSION macro which can be used to test which
> features are present in the libclc implementation the application is
> using.  That is, HISTORY for clc_foo() would say things like:
>    clc 1.1: New function.
>    clc 1.2: Added error code CLC_ENOMEM.
> 	Bugfix.
> Only the last bugfix need to be mentioned: It's enough that people can
> tell if they have a version which fixes all known bugs or not.

Good idea. We should commit to CVS on a file-by-file basis when bugfixes 
are done to a file.

BTW, I currently update the files NEWS and ChangeLog when a new release 
is created. Not very much, but at least something is written there.

> 
> Anyway, what should the CLC_VERSION macro be defined as?
> With 3 version levels, we need something like
>     #define CLC_VERSION_MAJOR    0
>     #define CLC_VERSION_MINOR    1
>     #define CLC_VERSION_REVISION 3
>     #define CLC_VERSION (1000000L * CLC_VERSION_MAJOR \
> 			 +  1000L * CLC_VERSION_MINOR \
> 			 + CLC_VERSION_REVISION)
> and code like
> #if CLC_VERSION < 1003005 / whatever / #else / something / #endif

#define'ing the version numbers makes it harder to keep version numbers 
and file names in sync. Since we sooner or later will start tagging the 
files in CVS, we have yet another possibility for version number errors.

If we end up using autoconf, then a version is available at compile time 
already (Unfortunately as a quoted string). Maybe some autoconf+m4 magic 
can create what we need automatically?

I have no solution to this. Anyone...?

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

Re: [Libclc-developers] clc_string module

[<bo...@me...>]

Hallvard B Furuseth wrote:
> 
> CVS access for 'hfuru' needed.  

hfuru added to the project with developer permissions. Not sure if that 
imples CVS access. Try it.

(Well, I assume it's the same user
> as I created at sf for the mailinglist?)
> And I need to find out my password; I have forgotten.
> There is one password I suspect, but if that isn't it I may
> have to build a new user:-(
> 
> sourceforge doesn't offer to mail my password to me, only a password
> hash which can be used for login.  Does anyone know how to get my
> plaintext password from sourceforge?

 From the support page:
Clicking "Send Lost PW Hash" below will email a URL to the email address 
we have on file for you. In this URL is a 128-bit confirmation hash for 
your account. Visiting the URL will allow you to change your password
online and login.                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^

If that can't help you, you may need to create a hfuru2 user?

-- 
boa

Please join the libclc-developers list
at http://lists.sourceforge.net/lists/listinfo/libclc-developers

Re: [Libclc-developers] clc_string module

[Hallvard B F. <h.b...@us...>]

Bj=F8rn Augestad writes:
>> Good point.  I don't know.  Anyway, will fix.
>=20
> How will you fix it?
>=20
> One solution is that you change it in CVS at sourceforge.

CVS access for 'hfuru' needed.  (Well, I assume it's the same user
as I created at sf for the mailinglist?)
And I need to find out my password; I have forgotten.
There is one password I suspect, but if that isn't it I may
have to build a new user:-(

sourceforge doesn't offer to mail my password to me, only a password
hash which can be used for login.  Does anyone know how to get my
plaintext password from sourceforge?

--=20
Hallvard