_        ___  ____ ____  ____        _        
  |_|_ _   / _ \/ ___/ ___||  _ \   ___| |_ _ __ 
  _|_||_| | | | \___ \___ \| |_) | / __| __| '__|
 |_||_|_| | |_| |___) |__) |  __/  \__ \ |_| |   
  |_|_|_|  \___/|____/____/|_|     |___/\__|_|   

  OSSP str - String Handling

  TODO

  o look at printf ideas from ../stdio/printf!!
  o look at ../strnatcmp
  o dynamic strings
  o aprintf() variant of str_format (see end of str_format.c!)

  The following *have* to be done before 1.0.0:

  o perhaps a str_shave() or str_strip() function which
    allows one to strip off characters out of a set from
    begin and end of a string. Usually for zapping whitespaces
    from begin and end of string.
    => str_shave(" \t foo bar ", " \t\n") => "foo bar"

  o use stdio-style "t" strings insead of STR_TRIGRAPH bitmasks
  o finish str_test.c: more tests
  o Dean wrote: btw -- str_compare taking a mode argument doesn't let you trim a few
    cycles by going into strcmp/strcasecmp which are usually hand-tuned
    assembly beasts on most boxes.  i'd go for str_compare and
    str_casecompare.

  The following *could* be done before 1.0.0:

  o Unicode/UTF-8 support!!
  o str_encode/str_decode:
    - plain base64
    - strict base64 (with newlines and padding, etc.)
  o str to/from symbol conversion:
    - long str_symbol(char *str);
  o str_format merged with strptime
  o str_locate could become a "mode" argument which
    indicates whether "s" is small or large and if
    it is small a (faster) brute force search could be done.
  o str_parse could support s/.../g or even m/.../g
  o one could add "vstr" support with own malloc
    Dean wrote: have you seen djb's stralloc stuff? it's part of qmail.
    it looks like a nice way to avoid thinking about lengths.

> I really like your Str library, but I have a question:
>
> What is its equivalent og the Perl 'g' modifier, such as in this example
> (Perl):
>
> $teststr = 'hello/world/nice/to/meet/you';
> $teststr =~ s/\//:/g;
> # $teststr == 'hello:world:nice:to:meet:you';
>
> I couldn't find it in the documentation. Has this been implemented yet?
> If not, is there some other way of doing it?

Hmmm... yes, I initially left our the /g variant because I thought just
about _matching_ like in m/.../g. But that was silly. You're right,
for s/.../ the global flag is very important. It is currently still
not implemented, but I've now added it to my TODO list for Str. OTOH
your s/\//:/g usually can be performed more easier without str_parse,
of course. Just use str_span() in a loop and replace the underlaying
character in each step until str_span reached the end of the string.

  o Feedback from http://www.and.org/vstr/comparison.html:

    The printf implementation is internal and based on the Apache
    snprintf() function, '\'' (thousand modifiers), 'a', 'F', 'Lf',
    'lld', 'td', 'zd', 'hhd' , etc. and i18n format parameter modifiers
    are all completely missing Unspecified precision is broken, as is
    corner cases for octal etc. also infinity/nan output is not correct
    with regard to case. Buffer overflows are possible in the integer
    formatting paths You can have custom modifiers, but only triggered
    on the system '%' character ... so gcc will currently spam warnings.
    It also looks like the ISO C std. is completely ignored for certain
    corner cases. Also note that due to the fact that the strings cannot
    be resized by the library the printf implementation uses a snprint()
    interface, this means that data can be lost using the interface if
    the programer isn't carefull.