var::String Class Reference
Inheritance diagram for var::String:

Documentation

This is an embedded friendly string class. It is similar to the C++ string type but is built on var::Data and cstring functions. The naming convention follows includes many std::string methods.

#include <sapi/var.hpp>
String s1;
String s2;
s1 = "This is my string";
s1 << " " << s1.capacity() << "\n";
printf("%s", s1.c_str());
//Strings can be compared
s2 = "This is another string";
if( s1 == s2 ){
printf("The strings are the same!\n");
} else {
printf("The strings are different\n");
}

The above code outputs:

This is my string 64
The strings are different

Public Member Functions

 String ()
 
 String (u32 capacity)
 
 String (const String &str)
 
 String (const char *s)
 
 String (const char *s, u32 len)
 
 String (char *mem, u32 capacity, bool readonly=false)
 
int append (const char *a)
 
int append (const String &a)
 
int append (char c)
 
int assign (const char *a, u32 subpos, u32 sublen)
 
int assign (const char *a, u32 n)
 
int assign (const char *a)
 
int assign (const String &a)
 
char at (u32 pos) const
 
float atoff () const
 
int atoi () const
 
int calc_delimited_data_size (char sep= ',', char term= '\n')
 
u32 capacity () const
 
int compare (const String &str) const
 
int compare (u32 pos, u32 len, const String &str) const
 
int compare (u32 pos, u32 len, const String &str, u32 subpos, u32 n) const
 
int compare (const char *str) const
 
int compare (u32 pos, u32 len, const char *s)
 
int compare (u32 pos, u32 len, const char *s, u32 n) const
 
u32 copy (char *s, u32 len, u32 pos=0) const
 
u32 copy (String &s, u32 n, u32 pos=0) const
 
Stringerase (u32 pos, u32 len=-1)
 
u32 find (const String &str, u32 pos=0) const
 
u32 find (const char *str, u32 pos=0) const
 
u32 find (const char c, u32 pos=0) const
 
u32 find (const char *s, u32 pos, u32 n) const
 
bool get_delimited_data (String &dest, int n, char sep= ',', char term= '\n')
 
Stringinsert (u32 pos, const char *s)
 
bool is_empty () const
 
u32 length () const
 
bool operator!= (const char *cmp) const
 
bool operator!= (const String &cmp) const
 
String operator+ (const String &a)
 
Stringoperator+= (const String &a)
 
Stringoperator+= (const char *a)
 
Stringoperator+= (char a)
 
Stringoperator<< (const char *a)
 
Stringoperator<< (const String &a)
 
Stringoperator<< (char c)
 
Stringoperator= (const String &a)
 
Stringoperator= (const char *a)
 
bool operator== (const char *cmp) const
 
bool operator== (const String &cmp) const
 
int print (u32 o_flags=PRINT_HEX) const
 
void push_back (char c)
 
u32 rfind (const String &str, u32 pos=0) const
 
u32 rfind (const char *str, u32 pos=0) const
 
u32 rfind (const char c, u32 pos=0) const
 
u32 rfind (const char *s, u32 pos, u32 n) const
 
int set_capacity (u32 s)
 
u32 size () const
 
int sprintf (const char *format,...)
 
const char * str () const
 
String substr (u32 pos=0, u32 len=npos) const
 
void to_lower ()
 
void to_upper ()
 
- Public Member Functions inherited from var::Data
 Data ()
 
 Data (const Data &a)
 
 Data (void *mem, u32 size, bool readonly=false)
 
 Data (u32 size)
 
virtual ~Data ()
 
int alloc (u32 size, bool resize=false)
 
virtual u32 calc_size () const
 
u32 capacity () const
 
char * cdata () const
 
const char * cdata_const () const
 
void clear ()
 
void * data () const
 
const void * data_const () const
 
virtual void fill (unsigned char d)
 
int free ()
 
bool is_internally_managed () const
 
bool is_read_only () const
 
Dataoperator= (const Data &a)
 
int resize (u32 size)
 
void set (void *mem, u32 size, bool readonly=false)
 
int set_capacity (u32 s)
 
void set_transfer_ownership ()
 
void swap_byte_order (int size=4)
 
- Public Member Functions inherited from api::WorkObject
void clear_error_number () const
 
int error_number () const
 

Additional Inherited Members

- Static Public Member Functions inherited from var::Data
static u32 minimum_size ()
 
- Static Public Member Functions inherited from api::ApiObject
static const char * api_version ()
 

Member Enumeration Documentation

anonymous enum
Enumerator
npos 

Defines an invalid string length and position

Constructor & Destructor Documentation

var::String::String ( )

Constructs an empty string and allocates the minimum capacity.

To construct a String without using any memory allocation us String(0).

var::String::String ( u32  capacity)

Declares an empty string of a specified capacity.

Parameters
capacityThe minimum capacity of the string.

If capacity is zero, no memory will be allocated to the string.

var::String::String ( const String str)
inline

Contructs a string as a copy of the string specified.

Parameters
strA reference to the string to copy.

if s is_internally_managed(), this object will allocate memory internally and copy the contents of str.

If str !is_internally_managed(), this object will refer to the same memory as str.

var::String::String ( const char *  s)

Declares a string and initialize to s.

var::String::String ( const char *  s,
u32  len 
)

Declares a string and initialize to s.

var::String::String ( char *  mem,
u32  capacity,
bool  readonly = false 
)

Constructs a string using statically allocated memory.

Parameters
memA pointer to memory to use
capacityThe number of bytes available
readonlyTrue if the mem is in readonly memory

Member Function Documentation

int var::String::append ( const char *  a)

Appends a (zero terminated) to string.

int var::String::append ( const String a)
inline

Appends a String to this string.

int var::String::append ( char  c)

Appends c to string.

int var::String::assign ( const char *  a,
u32  subpos,
u32  sublen 
)
inline

Assigns a substring of a to string.

int var::String::assign ( const char *  a,
u32  n 
)

Assigns a maximum of n characters of a to string.

int var::String::assign ( const char *  a)

Assigns a (zero terminated) to string.

int var::String::assign ( const String a)
inline

Assigns a to this String.

char var::String::at ( u32  pos) const

Returns character at pos.

float var::String::atoff ( ) const

Converts to a float.

int var::String::atoi ( ) const
inline

Converts to an integer.

String x = "10";
printf("X is %d\n", x.atoi());
int var::String::calc_delimited_data_size ( char  sep = ',',
char  term = '\n' 
)

Returns the number of elements in the String.

u32 var::String::capacity ( ) const

Returns the capacity of the string.

The capacity is the current number of bytes allocated in memory for the string. set_capacity() will increase the capacity of the string. The append() method will also increase the capacity of the String if the appended string needs the extra space.

int var::String::compare ( const String str) const

Compares the object to str.

Parameters
strA reference comparing string
Returns
Zero if the strings are the same
int var::String::compare ( u32  pos,
u32  len,
const String str 
) const

Compares the object to str.

Parameters
posThe position in this object to start the comparison
lenThe number of characters to compare
strA reference to the comparing string
Returns
Zero if the strings match
int var::String::compare ( u32  pos,
u32  len,
const String str,
u32  subpos,
u32  n 
) const

Compares the object to str.

Parameters
posThe position in this object to start the comparison
lenThe length of the compared string (this object)
strA reference to the comparing string
subposThe position in the comparing string to start comparing
nThe number os characters to compare
Returns
Zero if the strings match
int var::String::compare ( const char *  str) const

Compares the object to str.

Parameters
strA reference comparing string
Returns
Zero if the strings are the same
int var::String::compare ( u32  pos,
u32  len,
const char *  s 
)

Compares the object to str.

Parameters
posThe position in this object to start the comparison
lenThe length of the compared string (this object)
sThe characters to compare
Returns
Zero if the strings match
int var::String::compare ( u32  pos,
u32  len,
const char *  s,
u32  n 
) const

Compares the object to str.

Parameters
posThe position in this object to start the comparison
lenThe length of the compared string (this object)
sThe characters to compare
nThe number of characters to compare
Returns
Zero if the strings match
u32 var::String::copy ( char *  s,
u32  len,
u32  pos = 0 
) const

Copies a portion of the string to s.

u32 var::String::copy ( String s,
u32  n,
u32  pos = 0 
) const
inline

Copies a portion of this string to s.

String& var::String::erase ( u32  pos,
u32  len = -1 
)

Erases a portion of the string starting with the character at pos.

Parameters
posThe position to start erasing
lenThe number of characters to erase
Returns
A reference to this string.
u32 var::String::find ( const String str,
u32  pos = 0 
) const

Finds a var::String within the object.

Parameters
strThe String to find
posThe position to start searching
Returns
The position of the string or var::String::npos if the String was not found
u32 var::String::find ( const char *  str,
u32  pos = 0 
) const

Finds a c string within the object.

u32 var::String::find ( const char  c,
u32  pos = 0 
) const

Finds a character within the object.

u32 var::String::find ( const char *  s,
u32  pos,
u32  n 
) const

Finds a string within the object.

bool var::String::get_delimited_data ( String dest,
int  n,
char  sep = ',',
char  term = '\n' 
)

Copies the nth element (separated by sep) of the string to to dest.

String& var::String::insert ( u32  pos,
const char *  s 
)

Inserts s (zero terminated) into string at pos.

Parameters
posWhere to insert the string in this object (zero to insert at beginning)
sZero terminated string to insert

If pos is greater than length(), error_number() is set to EINVAL.

bool var::String::is_empty ( ) const
inline

Tests if string is empty.

u32 var::String::length ( ) const
inline

Returns the length of the string.

bool var::String::operator!= ( const char *  cmp) const
inline

Compares to a c-string (inequality).

bool var::String::operator!= ( const String cmp) const
inline

Compares to a var::String.

String var::String::operator+ ( const String a)
inline

Appends a string to this string and returns a new string.

String& var::String::operator+= ( const String a)
inline

Appends a string to this string.

String& var::String::operator+= ( const char *  a)
inline

Appends a string to this string.

String& var::String::operator+= ( char  a)
inline

Appends a character to this string.

String& var::String::operator<< ( const char *  a)
inline

Appends a c style string go the string.

The string will be resized to accept the string if needed.

String& var::String::operator<< ( const String a)
inline

Appends a var::String to this String.

The string will be resized to accept the string if needed.

String& var::String::operator<< ( char  c)
inline

Appends a character to the string.

String& var::String::operator= ( const String a)
inline

Assigns the value of a String to another String.

Parameters
aThe new String to assign
Returns
A reference to the destination String

This method will make a copy of the string in a new memory location rather than just using the data location of the source string.

String str1 = "hello";
String str2 = "goodbye";
str2 = str1; //both strings are now "hello"
String& var::String::operator= ( const char *  a)
inline

Assigns a c-string to a String.

bool var::String::operator== ( const char *  cmp) const
inline

Compares to a c-string.

bool var::String::operator== ( const String cmp) const
inline

Compares to a var::String.

int var::String::print ( u32  o_flags = PRINT_HEX) const
inlinevirtual

Prints the string on the standard output.

Parameters
o_flagsThis is ignored but is used to override Data::print
Returns
The total number of characters written to the stdout

Reimplemented from var::Data.

void var::String::push_back ( char  c)
inline

Appends c to string.

u32 var::String::rfind ( const String str,
u32  pos = 0 
) const

Finds a string within the string searching from right to left.

u32 var::String::rfind ( const char *  str,
u32  pos = 0 
) const

Finds a string within the string searching from right to left.

u32 var::String::rfind ( const char  c,
u32  pos = 0 
) const

Finds a character within the string searching from right to left.

u32 var::String::rfind ( const char *  s,
u32  pos,
u32  n 
) const

Finds a string within the string searching from right to left.

int var::String::set_capacity ( u32  s)

Sets the capacity of the string.

Parameters
sThe number of bytes to reserve to string capacity.
Returns
Less than zero on an error

If a String uses dynamic memory allocation, this method will increase the capacity of the String. If s is smaller than capacity(), this function return without changing the capacity.

u32 var::String::size ( ) const
inline

Returns the length of the string.

int var::String::sprintf ( const char *  format,
  ... 
)

Prints a formatted string to this String.

Parameters
formatFormatted string
Returns
Total number of characters written to the string

If the formatted string exceeds the length of the string capacity, the string will be resized to accomate the full formatted string.

const char* var::String::str ( ) const
inline

Returns a c-style string pointer.

String var::String::substr ( u32  pos = 0,
u32  len = npos 
) const

Gets a sub string of the string.

Parameters
posStarting position to look for the sub-string
lenThe number of bytes in the String to search
void var::String::to_lower ( )

Converts to lower case.

void var::String::to_upper ( )

Converts to upper case.