PTypes: string: manipulation

#include <ptypes.h>

// get/set length and misc.
int    length(const string& s);
char*  setlength(string&, int);
char*  unique(string&);
void   clear(string& s);
bool   isempty(const string& s);

// concatenate
void   concat(string& s, const char* sc, int catlen);

// copy (get substring by position and length)
string copy(const string& s, int from [, int cnt ] );

// insert string or character
void   ins(const char* s1, string& s, int at);
void   ins(char s1, string& s, int at);
void   ins(const string& s1, string& s, int at);
void   ins(const char* s1, int s1len, string& s, int at);

// delete substring
void   del(string& s, int at [, int cnt ] );

// find substring or character
int    pos(const char* s1, const string& s);
int    pos(char s1, const string& s);
int    pos(const string& s1, const string& s);
int    rpos(char s1, const string& s);

// compare substring
bool   contains(const char* s1, const string& s, int at);
bool   contains(char s1, const string& s, int at);
bool   contains(const string& s1, const string& s, int at);
bool   contains(const char* s1, int s1len, const string& s, int at);

int length(const string& s) returns the actual length of the string, not counting the terminating null-symbol.

char* setlength(string&, int) changes the actual length of the string. The content of the original string is preserved, however the content of extra characters added during reallocation is undefined. This function returns a pointer to a unique buffer (i.e. refcount is 1), like function unique() below. Even if the length of the string is not changing, setlength() guarantees to make the string unique.

char* unique(string&) makes the string buffer unique, i.e. a new buffer is allocated and data is copied if necessary, so that the reference count after calling this function is guaranteed to be 1. All string manipulation functions call unique() whenever a modification is made on the string buffer. You may need to call this function explicitly to obtain a character pointer to the buffer; in all other cases reference counting mechanism works transparently.

bool isempty(string&) returns true if the given string is empty. Using this function is preferable to comparing the string with empty string literal "".

clear(string&) makes the given string empty. Using this function is preferable to assigning an empty string literal "".

concat(string& s, const char* sc, int catlen) adds the given buffer sc of length catlen to the string object s. Use operators + and += instead to concatenate characters, null-terminated strings and string objects.

string copy(const string& s, int from [, int cnt ] ) returns a substring of s starting from position from and containing cnt characters. If cnt is omitted, the rest of the string s starting from position from is returned.

ins(..., string& s, int at) inserts a character, a null-terminated string, a string object or a buffer with specified length into string object s at the given position at. If the position is out of bounds, ins() does nothing.

del(string& s, int at [, int cnt ] ) deletes cnt characters starting from position at of the string s. If cnt is omitted, the rest of the string starting from at is deleted.

int pos(..., const string& s) returns the position of the first occurrence of a character, a null-terminated string or a string object (first parameter) in the source string s, or returns -1 if the substring is not found. Function rpos() performs reverse-search.

bool contains(..., const string& s, int at) returns true if the given character, null-terminated string or string object (first parameter) equals the substring of s at the given position at.

PTypes home