String Struct Reference

#include <String.h>

Overview

UTF-8 strings.

Remarks

Because Strings are encoded using UTF-8, they must not be treated as ASCII C strings. That is, a single Unicode code point will often span multiple chars. Be mindful of this when executing Range operations.

Strings are locale-ready, but Objectively does not enable locale by default. Call setlocale to enable localization.

Definition at line 69 of file String.h.

Inheritance diagram for String:

Properties
char *	chars
	The backing null-terminated UTF-8 encoded character array.
size_t	length
	The length of the String in bytes.
Object	object
	The superclass.
Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class.
unsigned int	magic
	A header to allow introspection of Object types.

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

Protected Attributes
StringInterface *	interface
	The interface.
Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface.

Related Symbols
OBJECTIVELY_EXPORT const char *	NameForStringEncoding (StringEncoding encoding)
OBJECTIVELY_EXPORT String *	str (const char *fmt,...)
	A convenience function for instantiating Strings.
OBJECTIVELY_EXPORT Order	StringCompare (const ident a, const ident b)
	A Comparator for sorting Strings.
OBJECTIVELY_EXPORT StringEncoding	StringEncodingForName (const char *name)

Property Details

chars

char* String::chars

The backing null-terminated UTF-8 encoded character array.

Definition at line 85 of file String.h.

interface

StringInterface* String::interface

protected

The interface.

Definition at line 80 of file String.h.

length

size_t String::length

The length of the String in bytes.

Definition at line 90 of file String.h.

object

Object String::object

The superclass.

Definition at line 74 of file String.h.

Method Details

_String()

Class * _String

(

void

)

The String archetype.

Returns

The String Class.

Definition at line 999 of file String.c.

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

appendBytes()

void appendBytes	(	String *	self,
		const uint8_t *	bytes,
		size_t	length,
		StringEncoding	encoding
	)

Appends the decoded contents of bytes.

Parameters

self	The String.
bytes	The bytes.
length	The length of bytes to decode.
encoding	The character encoding.

Definition at line 476 of file String.c.

                                                                                                    {
 
  if (bytes) {
 
    Transcode trans = {
      .to = STRING_ENCODING_UTF8,
      .from = encoding,
      .in = (char *) bytes,
      .length = length,
      .out = calloc(length * sizeof(Unicode) + 1, sizeof(char)),
      .size = length * sizeof(Unicode) + 1
    };
 
    assert(trans.out);
 
    const size_t size = transcode(&trans);
    assert(size < trans.size);
 
    trans.out[size] = '\0';
 
    $(self, appendCharacters, trans.out);
 
    free(trans.out);
  }
}

appendCharacters()

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

Appends the specified UTF-8 encoded C string.

Parameters

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

Definition at line 506 of file String.c.

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

appendFormat()

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

Appends the specified formatted string.

Parameters

self	The String.
fmt	The format string.

Definition at line 541 of file String.c.

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

appendString()

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

Appends the specified String to this String.

Parameters

self	The String.
string	The String to append.

Definition at line 555 of file String.c.

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

appendVaList()

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

Appends the specified format string.

Parameters

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

Definition at line 566 of file String.c.

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

compareTo()

Order compareTo	(	const String *	self,
		const String *	other,
		const Range	range
	)

Compares this String lexicographically to another.

Parameters

self	The String.
other	The String to compare to.
range	The character Range to compare.

Returns

The ordering of this String compared to other.

Definition at line 161 of file String.c.

                                                                                   {
 
  assert(range.location + range.length <= self->length);
 
  if (other) {
    const int i = strncmp(self->chars + range.location, other->chars, range.length);
    if (i == 0) {
      return OrderSame;
    }
    if (i > 0) {
      return OrderDescending;
    }
  }
 
  return OrderAscending;
}

componentsSeparatedByCharacters()

Array * componentsSeparatedByCharacters	(	const String *	self,
		const char *	chars
	)

Returns the components of this String that were separated by chars.

Parameters

self	The String.
chars	The separating characters.

Returns

An Array of substrings that were separated by chars.

Definition at line 182 of file String.c.

                                                                                     {
 
  assert(chars);
 
  Array *components = $(alloc(Array), init);
 
  Range search = { 0, self->length };
  Range result = $(self, rangeOfCharacters, chars, search);
 
  while (result.length) {
    search.length = result.location - search.location;
 
    String *component = $(self, substring, search);
    $(components, addObject, component);
    release(component);
 
    search.location = result.location + result.length;
    search.length = self->length - search.location;
 
    result = $(self, rangeOfCharacters, chars, search);
  }
 
  String *component = $(self, substring, search);
  $(components, addObject, component);
  release(component);
 
  return components;
}

componentsSeparatedByString()

Array * componentsSeparatedByString	(	const String *	self,
		const String *	string
	)

Returns the components of this String that were separated by string.

Parameters

self	The String.
string	The separating String.

Returns

An Array of substrings that were separated by string.

Definition at line 215 of file String.c.

                                                                                    {
 
  assert(string);
 
  return $(self, componentsSeparatedByCharacters, string->chars);
}

deleteCharactersInRange()

void deleteCharactersInRange	(	String *	self,
		const Range	range
	)

Deletes the characters within range from this String.

Parameters

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

Definition at line 581 of file String.c.

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

getData()

Data * getData	(	const String *	self,
		StringEncoding	encoding
	)

Returns a Data with this String's contents in the given encoding.

Parameters

self	The String.
encoding	The desired StringEncoding.

Returns

A Data with this String's contents in the given encoding.

Definition at line 226 of file String.c.

                                                                  {
 
  Transcode trans = {
    .to = encoding,
    .from = STRING_ENCODING_UTF8,
    .in = self->chars,
    .length = self->length,
    .out = calloc(self->length, sizeof(Unicode) / sizeof(char)),
    .size = self->length * sizeof(Unicode)
  };
 
  assert(trans.out);
 
  const size_t size = transcode(&trans);
  assert(size <= trans.size);
 
  return $$(Data, dataWithMemory, trans.out, size);
}

hasPrefix()

bool hasPrefix	(	const String *	self,
		const String *	prefix
	)

Checks this String for the given prefix.

Parameters

self	The String.
prefix	The Prefix to check.

Returns

True if this String starts with prefix, false otherwise.

Definition at line 249 of file String.c.

                                                                {
 
  if (prefix->length > self->length) {
    return false;
  }
 
  Range range = { 0, prefix->length };
  return $(self, compareTo, prefix, range) == OrderSame;
}

hasSuffix()

bool hasSuffix	(	const String *	self,
		const String *	suffix
	)

Checks this String for the given suffix.

Parameters

self	The String.
suffix	The suffix to check.

Returns

True if this String ends with suffix, false otherwise.

Definition at line 263 of file String.c.

                                                                {
 
  if (suffix->length > self->length) {
    return false;
  }
 
  Range range = { self->length - suffix->length, suffix->length };
  return $(self, compareTo, suffix, range) == OrderSame;
}

init()

String * init

(

String *

self

)

Initializes this String.

Parameters

self	The String.

Returns

The initialized String, or NULL on error.

Definition at line 598 of file String.c.

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

initWithBytes()

String * initWithBytes	(	String *	self,
		const uint8_t *	bytes,
		size_t	length,
		StringEncoding	encoding
	)

Initializes this String by decoding length of bytes.

Parameters

self	The String.
bytes	The bytes.
length	The length of bytes to decode.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 606 of file String.c.

                                                                                                         {
 
  self = $(self, init);
  if (self) {
    $(self, appendBytes, bytes, length, encoding);
  }
 
  return self;
}

initWithCapacity()

String * initWithCapacity	(	String *	self,
		size_t	capacity
	)

Initializes this String with the given capacity.

Parameters

self	The String.
capacity	The capacity, in bytes.

Returns

The initialized String, or NULL on error.

Definition at line 620 of file String.c.

                                                               {
 
  self = $(self, initWithMemory, NULL, 0);
  if (self) {
    self->capacity = capacity;
    if (self->capacity) {
      self->chars = calloc(self->capacity, sizeof(char));
      assert(self->chars);
    }
  }
 
  return self;
}

initWithCharacters()

String * initWithCharacters	(	String *	self,
		const char *	chars
	)

Initializes this String by copying chars.

Parameters

self	The String.
chars	The null-terminated, UTF-8 encoded C string.

Returns

The initialized String, or NULL on error.

Definition at line 638 of file String.c.

                                                                   {
 
  self = $(self, init);
  if (self) {
    $(self, appendCharacters, chars);
  }
 
  return self;
}

initWithContentsOfFile()

String * initWithContentsOfFile	(	String *	self,
		const char *	path,
		StringEncoding	encoding
	)

Initializes this String with the contents of the FILE at path.

Parameters

self	The String.
path	The path of the file to load.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 652 of file String.c.

                                                                                               {
 
  Data *data = $$(Data, dataWithContentsOfFile, path);
  if (data) {
    self = $(self, initWithData, data, encoding);
  } else {
    self = $(self, init);
  }
 
  release(data);
  return self;
}

initWithData()

String * initWithData	(	String *	self,
		const Data *	data,
		StringEncoding	encoding
	)

Initializes this String with the given Data.

Parameters

self	The String.
data	The Data object.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 669 of file String.c.

                                                                                     {
 
  assert(data);
 
  return $(self, initWithBytes, data->bytes, data->length, encoding);
}

initWithFormat()

String * initWithFormat	(	String *	self,
		const char *	fmt,
			...
	)

Initializes this String with the specified format string.

Parameters

self	The String.
fmt	The format string.

Returns

The initialized String, or NULL on error.

Definition at line 680 of file String.c.

                                                                  {
 
  self = $(self, init);
  if (self) {
 
    va_list args;
    va_start(args, fmt);
 
    $(self, appendVaList, fmt, args);
 
    va_end(args);
  }
 
  return self;
}

initWithMemory()

String * initWithMemory	(	String *	self,
		const ident	mem,
		size_t	length
	)

Initializes this String with the specified buffer.

Parameters

self	The String.
mem	The dynamically allocated null-terminated, UTF-8 encoded buffer.
length	The length of mem in printable characters.

Returns

The initialized String, or NULL on error.

Remarks

The memory will be freed when this String is deallocated.

Definition at line 700 of file String.c.

                                                                            {
 
  self = (String *) super(Object, self, init);
  if (self) {
    self->chars = (char *) mem;
    self->length = length;
    self->capacity = self->chars ? length + 1 : 0;
  }
 
  return self;
}

initWithString()

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

Initializes this String with the contents of string.

Parameters

self	The String.
string	A String.

Returns

The initialized String, or NULL on error.

Definition at line 716 of file String.c.

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

initWithVaList()

String * initWithVaList	(	String *	self,
		const char *	fmt,
		va_list	args
	)

Initializes this String with the specified arguments list.

Parameters

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

Returns

The initialized String, or NULL on error.

See also

vasprintf(3)

Definition at line 730 of file String.c.

                                                                           {
 
  self = $(self, init);
  if (self) {
    $(self, appendVaList, fmt, args);
  }
 
  return self;
}

insertCharactersAtIndex()

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

Inserts the specified String at the given index.

Parameters

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

Definition at line 744 of file String.c.

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

insertStringAtIndex()

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

Inserts the specified String at the given index.

Parameters

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

Definition at line 755 of file String.c.

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

lowercaseString()

String * lowercaseString

(

const String *

self

)

Parameters

self	The String.

Returns

A lowercase representation of this String.

Definition at line 281 of file String.c.

                                                   {
 
  Data *data = $(self, getData, STRING_ENCODING_WCHAR);
  assert(data);
 
  const size_t codepoints = data->length / sizeof(Unicode);
  Unicode *unicode = (Unicode *) data->bytes;
 
  for (size_t i = 0; i < codepoints; i++, unicode++) {
    *unicode = towlower(*unicode);
  }
 
  String *lowercase = $$(String, stringWithData, data, STRING_ENCODING_WCHAR);
 
  release(data);
  return lowercase;
}

rangeOfCharacters()

Range rangeOfCharacters	(	const String *	self,
		const char *	chars,
		const Range	range
	)

Finds and returns the first occurrence of chars in this String.

Parameters

self	The String.
chars	The characters to search for.
range	The Range in which to search.

Returns

A Range specifying the first occurrence of chars in this String.

Definition at line 303 of file String.c.

                                                                                         {
 
  assert(chars);
  assert(range.location > -1);
  assert(range.length > 0);
  assert(range.location + range.length <= self->length);
 
  Range match = { -1, 0 };
  const size_t len = strlen(chars);
 
  const char *str = self->chars + range.location;
  for (size_t i = 0; i < range.length; i++, str++) {
    if (strncmp(str, chars, len) == 0) {
      match.location = range.location + i;
      match.length = len;
      break;
    }
  }
 
  return match;
}

rangeOfString()

Range rangeOfString	(	const String *	self,
		const String *	string,
		const Range	range
	)

Finds and returns the first occurrence of string in this String.

Parameters

self	The String.
string	The String to search for.
range	The Range in which to search.

Returns

A Range specifying the first occurrence of string in this String.

Definition at line 329 of file String.c.

                                                                                        {
 
  assert(string);
 
  return $(self, rangeOfCharacters, string->chars, range);
}

replaceCharactersInRange()

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

Replaces the characters in range with the given characters.

Parameters

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

Definition at line 764 of file String.c.

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

replaceOccurrencesOfCharacters()

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

Replaces all occurrences of chars with the given replacement.

Parameters

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

Definition at line 788 of file String.c.

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

replaceOccurrencesOfCharactersInRange()

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

Replaces occurrences of chars in range with the given replacement.

Parameters

self	The String.
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 796 of file String.c.

                                                                                                                               {
 
  assert(chars);
  assert(replacement);
 
  assert(range.location >= 0);
  assert(range.location + range.length <= self->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	(	String *	self,
		const String *	string,
		const String *	replacement
	)

Replaces all occurrences of string with the given replacement.

Parameters

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

Definition at line 826 of file String.c.

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

replaceOccurrencesOfStringInRange()

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

Replaces occurrences of string in range with the given replacement.

Parameters

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

Definition at line 834 of file String.c.

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

replaceStringInRange()

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

Replaces the characters in range with the contents of string.

Parameters

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

Definition at line 846 of file String.c.

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

setCharacters()

void setCharacters	(	String *	self,
		const char *	chars
	)

Sets the contents of this String to chars.

Parameters

self	The String.
chars	The characters to set, or NULL.

Definition at line 855 of file String.c.

                                                           {
 
  $(self, setLength, 0);
 
  $(self, appendCharacters, chars);
}

setFormat() [1/2]

void setFormat	(	String *	self,
		const char *	fmt
	)

Sets the contents of this String to the formatted string.

Parameters

self	The String.
fmt	The format string.

setFormat() [2/2]

void setFormat	(	String *	self,
		const char *	fmt,
			...
	)

Definition at line 866 of file String.c.

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

setLength()

void setLength	(	String *	self,
		size_t	length
	)

Sets the length of this String to length.

Parameters

self	The String.
length	The length, which must be less than or equal to capacity.

Definition at line 882 of file String.c.

                                                   {
 
  if (length < self->length) {
    self->length = length;
    self->chars[length] = '\0';
  }
}

setString()

void setString	(	String *	self,
		const String *	string
	)

Sets the contents of this String to that of string.

Parameters

self	The String.
string	The String to set the contents from, or NULL.

Definition at line 894 of file String.c.

                                                          {
 
  $(self, setLength, 0);
 
  $(self, appendString, string);
}

string()

String * string

(

void

)

Returns a new String.

Returns

The new String, or NULL on error.

Definition at line 905 of file String.c.

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

stringWithBytes()

String * stringWithBytes	(	const uint8_t *	bytes,
		size_t	length,
		StringEncoding	encoding
	)

Returns a new String by decoding length of bytes to UTF-8.

Parameters

bytes	The bytes.
length	The length of bytes to copy.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 340 of file String.c.

                                                                                             {
 
  return $(alloc(String), initWithBytes, bytes, length, encoding);
}

stringWithCapacity()

String * stringWithCapacity

(

size_t

capacity

)

Returns a new String with the given capacity.

Parameters

capacity

The desired capacity, in bytes.

Returns

The new String, or NULL on error.

Definition at line 913 of file String.c.

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

stringWithCharacters()

String * stringWithCharacters

(

const char *

chars

)

Returns a new String by copying chars.

Parameters

chars

The null-terminated UTF-8 encoded C string.

Returns

The new String, or NULL on error.

Definition at line 349 of file String.c.

                                                       {
 
  return $(alloc(String), initWithCharacters, chars);
}

stringWithContentsOfFile()

String * stringWithContentsOfFile	(	const char *	path,
		StringEncoding	encoding
	)

Returns a new String with the contents of the FILE at path.

Parameters

path	A path name.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 358 of file String.c.

                                                                                   {
 
  return $(alloc(String), initWithContentsOfFile, path, encoding);
}

stringWithData()

String * stringWithData	(	const Data *	data,
		StringEncoding	encoding
	)

Returns a new String with the the given Data.

Parameters

data	A Data.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 367 of file String.c.

                                                                         {
 
  return $(alloc(String), initWithData, data, encoding);
}

stringWithFormat()

String * stringWithFormat

(

const char *

fmt

)

Returns a new String with the given format string.

Parameters

fmt	The format string.

Returns

The new String, or NULL on error.

stringWithMemory()

String * stringWithMemory	(	const ident	mem,
		size_t	length
	)

Returns a new String with the given buffer.

Parameters

mem	A dynamically allocated, null-terminated UTF-8 encoded buffer.
length	The length of mem in bytes.

Returns

The new String, or NULL on error.

Remarks

The memory will be freed when the returned String is deallocated.

Definition at line 392 of file String.c.

                                                                {
 
  return $(alloc(String), initWithMemory, mem, length);
}

substring()

String * substring	(	const String *	self,
		const Range	range
	)

Creates a new String from a subset of this one.

Parameters

self	The String.
range	The character Range.

Returns

The new String.

Definition at line 401 of file String.c.

                                                                {
 
  assert(range.location + range.length <= self->length);
 
  ident mem = calloc(range.length + 1, sizeof(char));
  assert(mem);
 
  strncpy(mem, self->chars + range.location, range.length);
 
  return $(alloc(String), initWithMemory, mem, range.length);
}

trim()

void trim

(

String *

self

)

Trims leading and trailing whitespace from this String.

Parameters

self	The String.

Definition at line 921 of file String.c.

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

trimmedString()

String * trimmedString

(

const String *

self

)

Creates a copy of this String with leading and trailing whitespace removed.

Parameters

self	The String.

Returns

The trimmed String.

Definition at line 417 of file String.c.

                                                 {
 
  Range range = { .location = 0, .length = self->length };
 
  while (isspace(self->chars[range.location])) {
    range.location++;
    range.length--;
  }
 
  while (range.length > 0 && isspace(self->chars[range.location + range.length - 1])) {
    range.length--;
  }
 
  return $(self, substring, range);
}

uppercaseString()

String * uppercaseString

(

const String *

self

)

Parameters

self	The String.

Returns

An uppercase representation of this String.

Definition at line 437 of file String.c.

                                                   {
 
  Data *data = $(self, getData, STRING_ENCODING_WCHAR);
  assert(data);
 
  const size_t codepoints = data->length / sizeof(Unicode);
  Unicode *unicode = (Unicode *) data->bytes;
 
  for (size_t i = 0; i < codepoints; i++, unicode++) {
    *unicode = towupper(*unicode);
  }
 
  String *uppercase = $$(String, stringWithData, data, STRING_ENCODING_WCHAR);
 
  release(data);
  return uppercase;
}

writeToFile()

bool writeToFile	(	const String *	self,
		const char *	path,
		StringEncoding	encoding
	)

Writes this String to path.

Parameters

self	The String.
path	The path of the file to write.
encoding	The character encoding.

Returns

true on success, false on error.

Definition at line 459 of file String.c.

                                                                                       {
 
  Data *data = $(self, getData, encoding);
  assert(data);
 
  const bool success = $(data, writeToFile, path);
 
  release(data);
  return success;
}

Related

NameForStringEncoding()

OBJECTIVELY_EXPORT const char * NameForStringEncoding ( StringEncoding  encoding )

related

Parameters

encoding

A StringEncoding.

Returns

The canonical name for the given encoding.

Definition at line 1019 of file String.c.

                                                           {
 
  switch (encoding) {
    case STRING_ENCODING_ASCII:
      return "ASCII";
    case STRING_ENCODING_LATIN1:
      return "ISO-8859-1";
    case STRING_ENCODING_LATIN2:
      return "ISO-8859-2";
    case STRING_ENCODING_MACROMAN:
      return "MacRoman";
    case STRING_ENCODING_UTF16:
      return "UTF-16";
    case STRING_ENCODING_UTF32:
      return "UTF-32";
    case STRING_ENCODING_UTF8:
      return "UTF-8";
    case STRING_ENCODING_WCHAR:
      return "WCHAR_T";
  }
 
  return "ASCII";
}

str()

OBJECTIVELY_EXPORT String * str ( const char *  fmt,   ...  )

related

A convenience function for instantiating Strings.

Parameters

fmt	The format string.

Returns

A new String, or NULL on error.

Definition at line 1084 of file String.c.

                                  {
 
  va_list args;
  va_start(args, fmt);
 
  String *string = $(alloc(String), initWithVaList, fmt, args);
  assert(string);
 
  va_end(args);
 
  return string;
}

StringCompare()

OBJECTIVELY_EXPORT Order StringCompare ( const ident  a, const ident  b  )

related

A Comparator for sorting Strings.

Parameters

a	A String.
b	A String.

Returns

The Order of a to b.

Definition at line 1066 of file String.c.

                                                  {
 
  if (a) {
    if (b) {
      const int i = strcmp(((String *) a)->chars, ((String *) b)->chars);
      if (i == 0) {
        return OrderSame;
      }
      if (i > 0) {
        return OrderDescending;
      }
    } else {
      return OrderDescending;
    }
  }
  return OrderAscending;
}

StringEncodingForName()

OBJECTIVELY_EXPORT StringEncoding StringEncodingForName ( const char *  name )

related

Parameters

name	The case-insensitive name of the encoding.

Returns

The StringEncoding for the given name.

Definition at line 1043 of file String.c.

                                                       {
 
  if (strcasecmp("ASCII", name) == 0) {
    return STRING_ENCODING_ASCII;
  } else if (strcasecmp("ISO-8859-1", name) == 0) {
    return STRING_ENCODING_LATIN1;
  } else if (strcasecmp("ISO-8859-2", name) == 0) {
    return STRING_ENCODING_LATIN2;
  } else if (strcasecmp("MacRoman", name) == 0) {
    return STRING_ENCODING_MACROMAN;
  } else if (strcasecmp("UTF-16", name) == 0) {
    return STRING_ENCODING_UTF16;
  } else if (strcasecmp("UTF-32", name) == 0) {
    return STRING_ENCODING_UTF32;
  } else if (strcasecmp("UTF-8", name) == 0) {
    return STRING_ENCODING_UTF8;
  } else if (strcasecmp("WCHAR", name) == 0) {
    return STRING_ENCODING_WCHAR;
  }
 
  return STRING_ENCODING_ASCII;
}

---

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

• Sources/Objectively/String.h
• Sources/Objectively/String.c