PROP_STRING(3)

PROP_STRING(3) | Library Functions Manual | PROP_STRING(3)

# NAME

`prop_string`, `prop_string_create`, `prop_string_create_cstring`, `prop_string_create_cstring_nocopy`, `prop_string_copy`, `prop_string_copy_mutable`, `prop_string_size`, `prop_string_mutable`, `prop_string_cstring`, `prop_string_cstring_nocopy`, `prop_string_append`, `prop_string_append_cstring`, `prop_string_equals`, `prop_string_equals_cstring` —
string value property object

# LIBRARY

Property Container Object Library (libprop, -lprop)

# SYNOPSIS

`#include <prop/proplib.h>`

prop_string_t
`prop_string_create`(void);

prop_string_t
`prop_string_create_cstring`(const char *cstring);

prop_string_t
`prop_string_create_cstring_nocopy`(const char *cstring);

prop_string_t
`prop_string_copy`(prop_string_t string);

prop_string_t
`prop_string_copy_mutable`(prop_string_t string);

size_t
`prop_string_size`(prop_string_t string);

bool
`prop_string_mutable`(prop_string_t string);

char *
`prop_string_cstring`(prop_string_t string);

const char *
`prop_string_cstring_nocopy`(prop_string_t string);

bool
`prop_string_append`(prop_string_t str1, prop_string_t str2);

bool
`prop_string_append_cstring`(prop_string_t string, const char *cstring);

bool
`prop_string_equals`(prop_string_t str1, prop_string_t str2);

bool
`prop_string_equals_cstring`(prop_string_t string, const char *cstring);

# DESCRIPTION

The `prop_string`() family of functions operate on a string value property object type.

`prop_string_create`(void)
  Create an empty mutable string. Returns `NULL` on failure.
`prop_string_create_cstring`(const char *cstring)
  Create a mutable string that contains a copy of cstring. Returns `NULL` on failure.
`prop_string_create_cstring_nocopy`(const char *cstring)
  Create an immutable string that contains a reference to cstring. Returns `NULL` on failure.
`prop_string_copy`(prop_string_t string)
  Copy a string. If the string being copied is an immutable external C string reference, then the copy is also immutable and references the same external C string. Returns `NULL` on failure.
`prop_string_copy_mutable`(prop_string_t string)
  Copy a string, always creating a mutable copy. Returns `NULL` on failure.
`prop_string_size`(prop_string_t string)
  Returns the size of the string, not including the terminating NUL. If the supplied object isn't a string, zero is returned.
`prop_string_mutable`(prop_string_t string)
  Returns `true` if the string is mutable. If the supplied object isn't a string, `false` is returned.
`prop_string_cstring`(prop_string_t string)
  Returns a copy of the string's contents as a C string. The caller is responsible for freeing the returned buffer.

  In user space, the buffer is allocated using malloc(3). In the kernel, the buffer is allocated using malloc(9) using the malloc type `M_TEMP`.

  Returns `NULL` on failure.

`prop_string_cstring_nocopy`(prop_string_t string)
  Returns an immutable reference to the contents of the string as a C string. If the supplied object isn't a string, `NULL` is returned.
`prop_string_append`(prop_string_t str1, prop_string_t str2)
  Append the contents of str2 to str1, which must be mutable. Returns `true` upon success and `false` otherwise.
`prop_string_append_cstring`(prop_string_t string, const char *cstring)
  Append the C string cstring to string, which must be mutable. Returns `true` upon success and `false` otherwise.
`prop_string_equals`(prop_string_t str1, prop_string_t str2)
  Returns `true` if the two string objects are equivalent.
`prop_string_equals_cstring`(prop_string_t string, const char *cstring)
  Returns `true` if the string's value is equivalent to cstring.

# SEE ALSO

prop_array(3), prop_bool(3), prop_data(3), prop_dictionary(3), prop_number(3), prop_object(3), proplib(3)

# HISTORY

The proplib(3) property container object library first appeared in NetBSD 4.0.

January 21, 2008 | NetBSD 9.0