allegro函数库

Better String library --------------------- by Paul Hsieh The bstring library is an attempt to provide improved string processing functionality to the C and C++ language. At the heart of the bstring library (Bstrlib for short) is the management of "bstring"s which are a significant improvement over '\0' terminated char buffers. =============================================================================== Motivation ---------- The standard C string library has serious problems: 1) Its use of '\0' to denote the end of the string means knowing a string's length is O(n) when it could be O(1). 2) It imposes an interpretation for the character value '\0'. 3) gets() always exposes the application to a buffer overflow. 4) strtok() modifies the string its parsing and thus may not be usable in programs which are re-entrant or multithreaded. 5) fgets has the unusual semantic of ignoring '\0's that occur before '\n's are consumed. 6) There is no memory management, and actions performed such as strcpy, strcat and sprintf are common places for buffer overflows. 7) strncpy() doesn't '\0' terminate the destination in some cases. 8) Passing NULL to C library string functions causes an undefined NULL pointer access. 9) Parameter aliasing (overlapping, or self-referencing parameters) within most C library functions has undefined behavior. 10) Many C library string function calls take integer parameters with restricted legal ranges. Parameters passed outside these ranges are not typically detected and cause undefined behavior. So the desire is to create an alternative string library that does not suffer from the above problems and adds in the following functionality: 1) Incorporate string functionality seen from other languages. a) MID$() - from BASIC b) split()/join() - from Python c) string/char x n - from Perl 2) Implement analogs to functions that combine stream IO and char buffers without creating a dependency on stream IO functionality. 3) Implement the basic text editor-style functions insert, delete, find, and replace. 4) Implement reference based sub-string access (as a generalization of pointer arithmetic.) 5) Implement runtime write protection for strings. There is also a desire to avoid "API-bloat". So functionality that can be implemented trivially in other functionality is omitted. So there is no left$() or right$() or reverse() or anything like that as part of the core functionality. Explaining Bstrings ------------------- A bstring is basically a header which wraps a pointer to a char buffer. Lets start with the declaration of a struct tagbstring: struct tagbstring { int mlen; int slen; unsigned char * data; }; This definition is considered exposed, not opaque (though it is neither necessary nor recommended that low level maintenance of bstrings be performed whenever the abstract interfaces are sufficient). The mlen field (usually) describes a lower bound for the memory allocated for the data field. The slen field describes the exact length for the bstring. The data field is a single contiguous buffer of unsigned chars. Note that the existence of a '\0' character in the unsigned char buffer pointed to by the data field does not necessarily denote the end of the bstring. To be a well formed modifiable bstring the mlen field must be at least the length of the slen field, and slen must be non-negative. Furthermore, the data field must point to a valid buffer in which access to the first mlen characters has been acquired. So the minimal check for correctness is: (slen >= 0 && mlen >= slen && data != NULL) bstrings returned by bstring functions can be assumed to be either NULL or satisfy the above property. (When bstrings are only readable, the mlen >= slen restriction is not required; this is discussed later in this section.) A bstring itself is just a pointer to a struct tagbstring: typedef struct tagbstring * bstring; Note that use of the prefix "tag" in struct tagbstring is required to work around the inconsistency between C and C++'s struct namespace usage. This definition is also considered exposed. Bstrlib basically manages bstrings allocated as a header and an associated data-buffer. Since the implementation is exposed, they can also be constructed manually. Functions which mutate bstrings assume that the header and data buffer have been malloced; the bstring library may perform al_free() or al_realloc() on both the header and data buffer of any bstring parameter. Functions which return bstring's create new bstrings. The string memory is freed by a bdestroy() call (or using the bstrFree macro). The following related typedef is also provided: typedef const struct tagbstring * const_bstring; which is also considered exposed. These are directly bstring compatible (no casting required) but are just used for parameters which are meant to be non-mutable. So in general, bstring parameters which are read as input but not meant to be modified will be declared as const_bstring, and bstring parameters which may be modified will be declared as bstring. This convention is recommended for user written functions as well. Since bstrings maintain interoperability with C library char-buffer style strings, all functions which modify, update or create bstrings also append a '\0' character into the position slen + 1. This trailing '\0' character is not required for bstrings input to the bstring functions; this is provided solely as a convenience for interoperability with standard C char-buffer functionality. Analogs for the ANSI C string library functions have been created when they are necessary, but have also been left out when they are not. In particular there are no functions analogous to fwrite, or puts just for the purposes of bstring. The ->data member of any string is exposed, and therefore can be used just as easily as char buffers for C functions which read strings. For those that wish to hand construct bstrings, the following should be kept in mind: 1) While bstrlib can accept constructed bstrings without terminating '\0' characters, the rest of the C language string library will not function properly on such non-terminated strings. This is obvious but must be kept in mind. 2) If it is intended that a constructed bstring be written to by the bstring library functions then the data portion should be allocated by the malloc function and the slen and mlen fields should be entered properly. The struct tagbstring header is not reallocated, and only freed by bdestroy. 3) Writing arbitrary '\0' characters at various places in the string will not modify its length as perceived by the bstring library functions. In fact, '\0' is a legitimate non-terminating character for a bstring to contain. 4) For read only parameters, bstring functions do not check the mlen. I.e., the minimal correctness requirements are reduced to: (slen >= 0 && data != NULL) Better pointer arithmetic ------------------------- One built-in feature of '\0' terminated char * strings, is that its very easy and fast to obtain a reference to the tail of any string using pointer arithmetic. Bstrlib does one better by providing a way to get a reference to any substring of a bstring (or any other length delimited block of memory.) So rather than just having pointer arithmetic, with bstrlib one essentially has segment arithmetic. This is achieved using the macro blk2tbstr() which builds a reference to a block of memory and the macro bmid2tbstr() which