MutableString Struct Reference

#include <MutableString.h>

Overview

Mutable UTF-8 strings.

Definition at line 40 of file MutableString.h.

Inheritance diagram for MutableString:

Properties
String	string
	The superclass. More...
Properties inherited from String
char *	chars
	The backing null-terminated UTF-8 encoded character array. More...
size_t	length
	The length of the String in bytes. More...
Object	object
	The superclass. More...
Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class. More...

Methods
Class *	_MutableString (void)
	The MutableString archetype. More...
void	appendCharacters (MutableString *self, const char *chars)
	Appends the specified UTF-8 encoded C string. More...
void	appendFormat (MutableString *self, const char *fmt,...)
	Appends the specified formatted string. More...
void	appendString (MutableString *self, const String *string)
	Appends the specified String to this MutableString. More...
void	appendVaList (MutableString *self, const char *fmt, va_list args)
	Appends the specified format string. More...
void	deleteCharactersInRange (MutableString *self, const Range range)
	Deletes the characters within range from this MutableString. More...
MutableString *	init (MutableString *self)
	Initializes this MutableString. More...
MutableString *	initWithCapacity (MutableString *self, size_t capacity)
	Initializes this MutableString with the given capacity. More...
MutableString *	initWithString (MutableString *self, const String *string)
	Initializes this MutableString with the contents of string. More...
void	insertCharactersAtIndex (MutableString *self, const char *chars, size_t index)
	Inserts the specified String at the given index. More...
void	insertStringAtIndex (MutableString *self, const String *string, size_t index)
	Inserts the specified String at the given index. More...
void	replaceCharactersInRange (MutableString *self, const Range range, const char *chars)
	Replaces the characters in range with the given characters. More...
void	replaceOccurrencesOfCharacters (MutableString *self, const char *chars, const char *replacement)
	Replaces all occurrences of chars with the given replacement. More...
void	replaceOccurrencesOfCharactersInRange (MutableString *self, const char *chars, const Range range, const char *replacement)
	Replaces occurrences of chars in range with the given replacement. More...
void	replaceOccurrencesOfString (MutableString *self, const String *string, const String *replacement)
	Replaces all occurrences of string with the given replacement. More...
void	replaceOccurrencesOfStringInRange (MutableString *self, const String *string, const Range range, const String *replacement)
	Replaces occurrences of string in range with the given replacement. More...
void	replaceStringInRange (MutableString *self, const Range range, const String *string)
	Replaces the characters in range with the contents of string. More...
MutableString *	string (void)
	Returns a new MutableString. More...
MutableString *	stringWithCapacity (size_t capacity)
	Returns a new MutableString with the given capacity. More...
void	trim (MutableString *self)
	Trims leading and trailing whitespace from this MutableString. More...
Methods inherited from String
Class *	_String (void)
	The String archetype. More...
Order	compareTo (const String *self, const String *other, const Range range)
	Compares this String lexicographically to another. More...
Array *	componentsSeparatedByCharacters (const String *self, const char *chars)
	Returns the components of this String that were separated by chars. More...
Array *	componentsSeparatedByString (const String *self, const String *string)
	Returns the components of this String that were separated by string. More...
Data *	getData (const String *self, StringEncoding encoding)
	Returns a Data with this String's contents in the given encoding. More...
_Bool	hasPrefix (const String *self, const String *prefix)
	Checks this String for the given prefix. More...
_Bool	hasSuffix (const String *self, const String *suffix)
	Checks this String for the given suffix. More...
String *	initWithBytes (String *self, const uint8_t *bytes, size_t length, StringEncoding encoding)
	Initializes this String by decoding length of bytes. More...
String *	initWithCharacters (String *self, const char *chars)
	Initializes this String by copying chars. More...
String *	initWithContentsOfFile (String *self, const char *path, StringEncoding encoding)
	Initializes this String with the contents of the FILE at path. More...
String *	initWithData (String *self, const Data *data, StringEncoding encoding)
	Initializes this String with the given Data. More...
String *	initWithFormat (String *self, const char *fmt,...)
	Initializes this String with the specified format string. More...
String *	initWithMemory (String *self, const ident mem, size_t length)
	Initializes this String with the specified buffer. More...
String *	initWithVaList (String *self, const char *fmt, va_list args)
	Initializes this String with the specified arguments list. More...
String *	lowercaseString (const String *self)
MutableString *	mutableCopy (const String *self)
Range	rangeOfCharacters (const String *self, const char *chars, const Range range)
	Finds and returns the first occurrence of chars in this String. More...
Range	rangeOfString (const String *self, const String *string, const Range range)
	Finds and returns the first occurrence of string in this String. More...
String *	stringWithBytes (const uint8_t *bytes, size_t length, StringEncoding encoding)
	Returns a new String by decoding length of bytes to UTF-8. More...
String *	stringWithCharacters (const char *chars)
	Returns a new String by copying chars. More...
String *	stringWithContentsOfFile (const char *path, StringEncoding encoding)
	Returns a new String with the contents of the FILE at path. More...
String *	stringWithData (const Data *data, StringEncoding encoding)
	Returns a new String with the the given Data. More...
String *	stringWithFormat (const char *fmt)
	Returns a new String with the given format string. More...
String *	stringWithMemory (const ident mem, size_t length)
	Returns a new String with the given buffer. More...
String *	substring (const String *string, const Range range)
	Creates a new String from a subset of this one. More...
String *	trimmedString (const String *self)
	Creates a copy of this String with leading and trailing whitespace removed. More...
String *	uppercaseString (const String *self)
_Bool	writeToFile (const String *self, const char *path, StringEncoding encoding)
	Writes this String to path. More...
Methods inherited from Object
Class *	_Object (void)
	The Object archetype. More...
Object *	copy (const Object *self)
	Creates a shallow copy of this Object. More...
void	dealloc (Object *self)
	Frees all resources held by this Object. More...
String *	description (const Object *self)
int	hash (const Object *self)
Object *	init (Object *self)
	Initializes this Object. More...
_Bool	isEqual (const Object *self, const Object *other)
	Tests equality of the other Object. More...
_Bool	isKindOfClass (const Object *self, const Class *clazz)
	Tests for Class hierarchy membership. More...

Protected Attributes
MutableStringInterface *	interface
	The interface. More...
Protected Attributes inherited from String
StringInterface *	interface
	The interface. More...
Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface. More...

Additional Inherited Members
Related Functions inherited from String
OBJECTIVELY_EXPORT MutableString *	mstr (const char *fmt,...)
	A convenience function for instantiating MutableStrings. More...
OBJECTIVELY_EXPORT const char *	NameForStringEncoding (StringEncoding encoding)
OBJECTIVELY_EXPORT String *	str (const char *fmt,...)
	A convenience function for instantiating Strings. More...
OBJECTIVELY_EXPORT Order	StringCompare (const ident a, const ident b)
	A Comparator for sorting Strings. More...
OBJECTIVELY_EXPORT StringEncoding	StringEncodingForName (const char *name)

Property Details

interface

MutableStringInterface* MutableString::interface

protected

The interface.

Definition at line 51 of file MutableString.h.

string

MutableString * string

(

void

)

The superclass.

Definition at line 45 of file MutableString.h.

Method Details

_MutableString()

Class * _MutableString

(

void

)

The MutableString archetype.

Returns

The MutableString Class.

Definition at line 359 of file MutableString.c.

                            {
    static Class *clazz;
    static Once once;
 
    do_once(&once, {
        clazz = _initialize(&(const ClassDef) {
            .name = "MutableString",
            .superclass = _String(),
            .instanceSize = sizeof(MutableString),
            .interfaceOffset = offsetof(MutableString, interface),
            .interfaceSize = sizeof(MutableStringInterface),
            .initialize = initialize,
        });
    });
 
    return clazz;
}

appendCharacters()

void appendCharacters	(	MutableString *	self,
		const char *	chars
	)

Appends the specified UTF-8 encoded C string.

Parameters

self	The MutableString.
chars	A UTF-encoded C string.

Definition at line 54 of file MutableString.c.

                                                                     {
 
    if (chars) {
 
        const size_t len = strlen(chars);
        if (len) {
 
            const size_t newSize = self->string.length + strlen(chars) + 1;
            const size_t newCapacity = (newSize / _pageSize + 1) * _pageSize;
 
            if (newCapacity > self->capacity) {
 
                if (self->string.length) {
                    self->string.chars = realloc(self->string.chars, newCapacity);
                } else {
                    self->string.chars = malloc(newCapacity);
                }
 
                assert(self->string.chars);
                self->capacity = newCapacity;
            }
 
            ident ptr = self->string.chars + self->string.length;
            memmove(ptr, chars, len);
 
            self->string.chars[newSize - 1] = '\0';
            self->string.length += len;
        }
    }
}

appendFormat()

void appendFormat	(	MutableString *	self,
		const char *	fmt,
			...
	)

Appends the specified formatted string.

Parameters

self	The MutableString.
fmt	The format string.

Definition at line 89 of file MutableString.c.

                                                                    {
 
    va_list args;
    va_start(args, fmt);
 
    $(self, appendVaList, fmt, args);
 
    va_end(args);
}

appendString()

void appendString	(	MutableString *	self,
		const String *	string
	)

Appends the specified String to this MutableString.

Parameters

self	The MutableString.
string	The String to append.

Definition at line 103 of file MutableString.c.

                                                                    {
 
    if (string) {
        $(self, appendCharacters, string->chars);
    }
}

appendVaList()

void appendVaList	(	MutableString *	self,
		const char *	fmt,
		va_list	args
	)

Appends the specified format string.

Parameters

self	The MutableString.
fmt	The format string.
args	The format arguments.

Definition at line 114 of file MutableString.c.

                                                                             {
    char *chars;
 
    const int len = vasprintf(&chars, fmt, args);
    if (len > 0) {
        $(self, appendCharacters, chars);
    }
 
    free(chars);
}

deleteCharactersInRange()

void deleteCharactersInRange	(	MutableString *	self,
		const Range	range
	)

Deletes the characters within range from this MutableString.

Parameters

self	The MutableString.
range	The Range of characters to delete.

Definition at line 129 of file MutableString.c.

                                                                            {
 
    assert(range.location >= 0);
    assert(range.length <= self->string.length);
 
    ident ptr = self->string.chars + range.location;
    const size_t length = self->string.length - range.location - range.length + 1;
 
    memmove(ptr, ptr + range.length, length);
 
    self->string.length -= range.length;
}

init()

MutableString * init

(

MutableString *

self

)

Initializes this MutableString.

Parameters

self	The MutableString.

Returns

The initialized MutableString, or NULL on error.

Definition at line 146 of file MutableString.c.

                                                {
    return $(self, initWithCapacity, 0);
}

initWithCapacity()

MutableString * initWithCapacity	(	MutableString *	self,
		size_t	capacity
	)

Initializes this MutableString with the given capacity.

Parameters

self	The MutableString.
capacity	The capacity, in bytes.

Returns

The initialized MutableString, or NULL on error.

Definition at line 154 of file MutableString.c.

                                                                             {
 
    self = (MutableString *) super(String, self, initWithMemory, NULL, 0);
    if (self) {
        if (capacity) {
            self->string.chars = calloc(capacity, sizeof(char));
            assert(self->string.chars);
 
            self->capacity = capacity;
        }
    }
 
    return self;
}

initWithString()

MutableString * initWithString	(	MutableString *	self,
		const String *	string
	)

Initializes this MutableString with the contents of string.

Parameters

self	The MutableString.
string	A String.

Returns

The initialized MutableString, or NULL on error.

Definition at line 173 of file MutableString.c.

                                                                                {
 
    self = $(self, init);
    if (self) {
        $(self, appendString, string);
    }
 
    return self;
}

insertCharactersAtIndex()

void insertCharactersAtIndex	(	MutableString *	self,
		const char *	chars,
		size_t	index
	)

Inserts the specified String at the given index.

Parameters

self	The MutableString.
chars	The null-terminated UTF-8 encoded C string to insert.
index	The index.

Definition at line 187 of file MutableString.c.

                                                                                          {
 
    const Range range = { .location = index };
 
    $(self, replaceCharactersInRange, range, chars);
}

insertStringAtIndex()

void insertStringAtIndex	(	MutableString *	self,
		const String *	string,
		size_t	index
	)

Inserts the specified String at the given index.

Parameters

self	The MutableString.
string	The String to insert.
index	The index.

Definition at line 198 of file MutableString.c.

                                                                                         {
 
    $(self, insertCharactersAtIndex, string->chars, index);
}

replaceCharactersInRange()

void replaceCharactersInRange	(	MutableString *	self,
		const Range	range,
		const char *	chars
	)

Replaces the characters in range with the given characters.

Parameters

self	The MutableString.
range	The Range of characters to replace.
chars	The null-terminated UTF-8 encoded C string to substitute.

Definition at line 207 of file MutableString.c.

                                                                                                {
 
    assert(range.location >= 0);
    assert(range.location + range.length <= self->string.length);
 
    if (self->capacity == 0) {
        $(self, appendCharacters, chars);
    } else {
        char *remainder = strdup(self->string.chars + range.location + range.length);
 
        self->string.length = range.location;
        self->string.chars[range.location + 1] = '\0';
 
        $(self, appendCharacters, chars);
        $(self, appendCharacters, remainder);
 
        free(remainder);
    }
}

replaceOccurrencesOfCharacters()

void replaceOccurrencesOfCharacters	(	MutableString *	self,
		const char *	chars,
		const char *	replacement
	)

Replaces all occurrences of chars with the given replacement.

Parameters

self	The MutableString.
chars	The null-terminated UTF-8 encoded C string to replace.
replacement	The null-terminated UTF-8 encoded C string replacement.

Definition at line 231 of file MutableString.c.

                                                                                                            {
    $(self, replaceOccurrencesOfCharactersInRange, chars, (Range) { .length = self->string.length }, replacement);
}

replaceOccurrencesOfCharactersInRange()

void replaceOccurrencesOfCharactersInRange	(	MutableString *	self,
		const char *	chars,
		const Range	range,
		const char *	replacement
	)

Replaces occurrences of chars in range with the given replacement.

Parameters

self	The MutableString.
chars	The null-terminated UTF-8 encoded C string to replace.
range	The Range in which to replace.
replacement	The null-terminated UTF-8 encoded C string replacement.

Definition at line 239 of file MutableString.c.

                                                                                                                                      {
 
    assert(chars);
    assert(replacement);
 
    assert(range.location >= 0);
    assert(range.location + range.length <= self->string.length);
 
    Range search = range;
    while (true) {
 
        const Range result = $((String *) self, rangeOfCharacters, chars, search);
        if (result.location == -1) {
            break;
        }
 
        $(self, replaceCharactersInRange, result, replacement);
 
        search.length -= (result.location - search.location);
        search.length -= strlen(replacement);
        search.length += ((int) strlen(replacement) - (int) strlen(chars));
 
        search.location = result.location + strlen(replacement);
    }
}

replaceOccurrencesOfString()

void replaceOccurrencesOfString	(	MutableString *	self,
		const String *	string,
		const String *	replacement
	)

Replaces all occurrences of string with the given replacement.

Parameters

self	The MutableString.
string	The String to replace.
replacement	The String replacement.

Definition at line 269 of file MutableString.c.

                                                                                                             {
    $(self, replaceOccurrencesOfStringInRange, string, (Range) { .length = self->string.length }, replacement);
}

replaceOccurrencesOfStringInRange()

void replaceOccurrencesOfStringInRange	(	MutableString *	self,
		const String *	string,
		const Range	range,
		const String *	replacement
	)

Replaces occurrences of string in range with the given replacement.

Parameters

self	The MutableString.
string	The String to replace.
range	The Range in which to replace.
replacement	The String replacement.

Definition at line 277 of file MutableString.c.

                                                                                                                                       {
 
    assert(string);
    assert(replacement);
 
    $(self, replaceOccurrencesOfCharactersInRange, string->chars, range, replacement->chars);
}

replaceStringInRange()

void replaceStringInRange	(	MutableString *	self,
		const Range	range,
		const String *	string
	)

Replaces the characters in range with the contents of string.

Parameters

self	The MutableString.
range	The Range of characters to replace.
string	The String to substitute.

Definition at line 289 of file MutableString.c.

                                                                                               {
 
    $(self, replaceCharactersInRange, range, string->chars);
}

string()

MutableString * string

(

void

)

Returns a new MutableString.

Returns

The new MutableString, or NULL on error.

Definition at line 298 of file MutableString.c.

                                   {
 
    return $(alloc(MutableString), init);
}

stringWithCapacity()

MutableString * stringWithCapacity

(

size_t

capacity

)

Returns a new MutableString with the given capacity.

Parameters

capacity

The desired capacity, in bytes.

Returns

The new MutableString, or NULL on error.

Definition at line 307 of file MutableString.c.

                                                          {
 
    return $(alloc(MutableString), initWithCapacity, capacity);
}

trim()

void trim

(

MutableString *

self

)

Trims leading and trailing whitespace from this MutableString.

Parameters

self	The MutableString.

Definition at line 316 of file MutableString.c.

                                      {
 
    String *trimmed = $((String *) self, trimmedString);
 
    $(self, replaceStringInRange, (const Range) { .length = self->string.length }, trimmed);
 
    release(trimmed);
}

---

The documentation for this struct was generated from the following files:

• Sources/Objectively/MutableString.h
• Sources/Objectively/MutableString.c