String

Offers type to wrap constant strings or substrings into an object.

Summary

String	Offers type to wrap constant strings or substrings into an object.
Copyright	This program is free software.
Files
C-kern/api/string/string.h	Header file of String.
C-kern/string/string.c	Implementation file String impl.
Types
struct string_t	Export string_t.
Functions
test
unittest_string	Test <escapechar_string>.
string_t	Points to memory which contains a constant string.
addr	Start address of non-const string memory.
size	Size in bytes of memory.
lifetime
string_FREE	Static initializer.
string_INIT	Static initializer.
string_INIT_CSTR	Static initializer.
init_string	Assigns constant string buffer to str.
initcopy_string	Copies content of srcstr to str.
initfl_string	Assigns static string buffer to str.
initse_string	Assigns static string buffer to str.
initsubstr_string	Initializes str with substring of fromstr.
initfromstringstream_string	Initializes str with content of stringstream_t.
free_string	Sets string to string_FREE.
query
isfree_string	Returns true if string has address and size of 0.
isempty_string	Returns true if string has size 0.
addr_string	Returns the start address of the string in memory.
size_string	Returns size in bytes of string.
findbyte_string	Finds byte in string.
compare
isequalasciicase_string	Returns true if two strings compare equal in a case insensitive way.
change
substr_string	The string is made a substring of itself.
shrinkleft_string	Shrinks size of string by skipping bytes from the start.
shrinkright_string	Shrinks size of string by decrementing its size.
skipbyte_string	Increments the start address of the string by one and decrements its size.
generic
genericcast_string	Casts a pointer to generic obj type into pointer to string_t.
inline implementation
string_t
addr_string	Implements string_t.addr_string.
findbyte_string	Implements string_t.findbyte_string.
free_string	Implements string_t.free_string.
genericcast_string	Implements string_t.genericcast_string.
init_string	Implements string_t.init_string.
initcopy_string	Implements string_t.initcopy_string.
isempty_string	Implements string_t.isempty_string.
isfree_string	Implements string_t.isfree_string.
size_string	Implements string_t.size_string.
skipbyte_string	Implements string_t.skipbyte_string.

Copyright

This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Author

Files

C-kern/api/string/string.h

Header file of String.

C-kern/string/string.c

Implementation file String impl.

Types

struct string_t

typedef struct string_t string_t

Export string_t.

Functions

Summary

test
unittest_string	Test <escapechar_string>.

test

unittest_string

int unittest_string( void )

Test <escapechar_string>.

string_t

struct string_t

Points to memory which contains a constant string. This string does not include a trailing ‘\0’ byte. Null bytes are allowed in the string cause size describes the length of string and not any implicit trailing \0 byte. If you want to convert this string into a C string, i.e. either (char *) or cstring_t make sure that it does not contain any \0 byte.

Empty string

The empty string is represented as

{ "", 0 }

The size does not include any trailing ‘\0’ byte.

Undefined string

The undefined (or null) string is represented as

{ 0, 0 }

Summary

addr	Start address of non-const string memory.
size	Size in bytes of memory.
lifetime
string_FREE	Static initializer.
string_INIT	Static initializer.
string_INIT_CSTR	Static initializer.
init_string	Assigns constant string buffer to str.
initcopy_string	Copies content of srcstr to str.
initfl_string	Assigns static string buffer to str.
initse_string	Assigns static string buffer to str.
initsubstr_string	Initializes str with substring of fromstr.
initfromstringstream_string	Initializes str with content of stringstream_t.
free_string	Sets string to string_FREE.
query
isfree_string	Returns true if string has address and size of 0.
isempty_string	Returns true if string has size 0.
addr_string	Returns the start address of the string in memory.
size_string	Returns size in bytes of string.
findbyte_string	Finds byte in string.
compare
isequalasciicase_string	Returns true if two strings compare equal in a case insensitive way.
change
substr_string	The string is made a substring of itself.
shrinkleft_string	Shrinks size of string by skipping bytes from the start.
shrinkright_string	Shrinks size of string by decrementing its size.
skipbyte_string	Increments the start address of the string by one and decrements its size.
generic
genericcast_string	Casts a pointer to generic obj type into pointer to string_t.

addr

const uint8_t * addr

Start address of non-const string memory.

size

size_t size

Size in bytes of memory. The number of characters is lower or equal to this value.

lifetime

string_FREE

#define string_FREE { 0, 0 }

Static initializer. Sets string_t to null.

string_INIT

#define string_INIT( strsize,
straddr ) { (straddr), (strsize) }

Static initializer. Assigns static string buffer to string_t.

Parameter

strsize	The length in bytes of the substring. The number of characters represented is usually less then its size (a character can be represented with multiple bytes).
straddr	The start address of the string.

string_INIT_CSTR

#define string_INIT_CSTR( cstr ) { (const uint8_t*)(cstr), strlen(cstr) }

Static initializer. Sets string_t to address of cstr and size to strlen(cstr).

Example

const char   * buffer = "teststring" ;
string_t     str      = string_INIT_CSTR(buffer) ;

init_string

static inline void init_string( /*out*/string_t * str,
size_t size,
const uint8_t string[size] )

Assigns constant string buffer to str.

Expected parameter

str	pointer to string_t object which is initialized
size	Length of string in bytes
string	Address of first character.

initcopy_string

static inline void initcopy_string( /*out*/string_t * str,
const string_t * restrict srcstr )

Copies content of srcstr to str. The two string objects are not allowed to overlap. Only references are copied. The characters in memory are not copied.

initfl_string

int initfl_string( /*out*/string_t * str,
const uint8_t * first,
const uint8_t * last )

Assigns static string buffer to str. To initialize as empty string set last to a value smaller first. If first == last the size of the string is one.

Expected parameter

str	pointer to string_t object which is initialized
first	Address of first character.
last	Address of last character.

initse_string

int initse_string( /*out*/string_t * str,
const uint8_t * start,
const uint8_t * end )

Assigns static string buffer to str.

Expected parameter

str	pointer to string_t object which is initialized
start	Address of first character.
end	Address of memory after last character.

initsubstr_string

int initsubstr_string( /*out*/string_t * str,
const string_t * restrict fromstr,
size_t start_offset,
size_t size )

Initializes str with substring of fromstr. Same as calling <initcopy_string>(str,fromstr) and then calling <substr_string>(str,start_offset,size).

initfromstringstream_string

void initfromstringstream_string( /*out*/string_t * str,
const struct stringstream_t * strstream )

Initializes str with content of stringstream_t. The string points to the unread string buffer of stringstream_t.

free_string

void free_string( string_t * str )

Sets string to string_FREE.

query

isfree_string

bool isfree_string( const string_t * str )

Returns true if string has address and size of 0.

isempty_string

bool isempty_string( const string_t * str )

Returns true if string has size 0. A string initialized with string_FREE is considered an empty string. Use isfree_string to check if it is uninitialized.

addr_string

const uint8_t * addr_string( const string_t * str )

Returns the start address of the string in memory. The start address is the lowest address in memory. To access the second byte of the string use

string_t str = string_INIT(...) ;
uint8_t  seconde_byte = addr_string(&str)[1] ;

size_string

size_t size_string( const string_t * str )

Returns size in bytes of string. The size is not the same as the number of contained characters. A character can occupy more than one byte in memory so the size of a string is the upper limit of the number of contained characters.

findbyte_string

const uint8_t * findbyte_string( const string_t * str,
uint8_t byte )

Finds byte in string. The returned value points to the position of the found byte. The value 0 is returned if str does not contain the byte.

compare

isequalasciicase_string

bool isequalasciicase_string( const string_t * str,
const string_t * str2 )

Returns true if two strings compare equal in a case insensitive way. This functions assumes only ‘A’-’Z’ and ‘a’-’z’ as case sensitive characters.

change

substr_string

int substr_string( string_t * str,
size_t start_offset,
size_t size )

The string is made a substring of itself. Call initsubstr_string if you want to keep the original. If the precondition fails EINVAL is returned.

Parameter

start_offset	The start address of substring relative to the previous start address (see addr_string). This value must be smaller or equal than <size_string>(str).
size	The size (length) in number of bytes of the substring. This value must be smaller or equal than (<size_string>(str)-start_offset).

shrinkleft_string

int shrinkleft_string( string_t * str,
size_t nr_bytes_removed_from_string_start )

Shrinks size of string by skipping bytes from the start. Increments the start address of the string and decrements its size by nr_bytes_removed_from_string_start. The parameter nr_bytes_removed_from_string_start must be smaller or equal to <size_string>(str). If the precondition fails EINVAL is returned.

shrinkright_string

int shrinkright_string( string_t * str,
size_t nr_bytes_removed_from_string_end )

Shrinks size of string by decrementing its size. The parameter nr_bytes_removed_from_string_end must be smaller or equal to <size_string>(str). If the precondition fails EINVAL is returned. After successfull return the size is decremented by nr_bytes_removed_from_string_end. The start address of the string keeps the same.

skipbyte_string

void skipbyte_string( string_t * str )

Increments the start address of the string by one and decrements its size.

Attention

Call this function only if you know that isempty_string does return false.

generic

genericcast_string

const string_t * genericcast_string( const void * obj )

Casts a pointer to generic obj type into pointer to string_t.

inline implementation

Summary

string_t
addr_string	Implements string_t.addr_string.
findbyte_string	Implements string_t.findbyte_string.
free_string	Implements string_t.free_string.
genericcast_string	Implements string_t.genericcast_string.
init_string	Implements string_t.init_string.
initcopy_string	Implements string_t.initcopy_string.
isempty_string	Implements string_t.isempty_string.
isfree_string	Implements string_t.isfree_string.
size_string	Implements string_t.size_string.
skipbyte_string	Implements string_t.skipbyte_string.