azure-c-shared-utility/devdoc/strings_requirements.md

strings requirements

Overview

The STRING object encapsulates a char* variable. This interface is access by STRING_HANDLE variables that provide further encapsulation of the interface.

Exposed API

typedef void* STRING_HANDLE;


typedef void* STRING_HANDLE;

extern STRING_HANDLE STRING_new(void);
extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);
extern STRING_HANDLE STRING_construct(const char* psz);
extern STRING_HANDLE STRING_construct_n(const char* psz, size_t n);
extern STRING_HANDLE STRING_new_with_memory(const char* memory);
extern STRING_HANDLE STRING_new_quoted(const char* source);
extern STRING_HANDLE STRING_new_JSON(const char* source);
extern STRING_HANDLE STRING_from_byte_array(const unsigned char* source, size_t size);
extern void STRING_delete(STRING_HANDLE handle);
extern int STRING_concat(STRING_HANDLE handle, const char* s2);
extern int STRING_concat_with_STRING(STRING_HANDLE s1, STRING_HANDLE s2);
extern int STRING_quote(STRING_HANDLE handle);
extern int STRING_copy(STRING_HANDLE s1, const char* s2);
extern int STRING_copy_n(STRING_HANDLE s1, const char* s2, size_t n);
extern const char* STRING_c_str(STRING_HANDLE handle);
extern int STRING_empty(STRING_HANDLE handle);
extern size_t STRING_length(STRING_HANDLE handle);
extern int STRING_compare(STRING_HANDLE h1, STRING_HANDLE h2);
extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);
extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);

STRING_new

extern STRING_HANDLE STRING_new(void);

SRS_STRING_07_001: [ STRING_new shall allocate a new STRING_HANDLE pointing to an empty string. ]

SRS_STRING_07_002: [ STRING_new shall return an NULL STRING_HANDLE on any error that is encountered. ]

STRING_clone

extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);

SRS_STRING_02_001: [ STRING_clone shall produce a new string having the same content as the handle string. ]

SRS_STRING_02_002: [ If parameter handle is NULL then STRING_clone shall return NULL. ]

SRS_STRING_02_003: [ If STRING_clone fails for any reason, it shall return NULL. ]

STRING_construct

extern STRING_HANDLE STRING_construct(const char*)

SRS_STRING_07_003: [ STRING_construct shall allocate a new string with the value of the specified const char*. ]

SRS_STRING_07_005: [ If the supplied const char* is NULL STRING_construct shall return a NULL value. ]

SRS_STRING_07_032: [ STRING_construct encounters any error it shall return a NULL value. ]

STRING_new_with_memory

extern STRING_HANDLE STRING_new_with_memory(char*)

SRS_STRING_07_006: [ STRING_new_with_memory shall return a STRING_HANDLE by using the supplied char* memory. ]

SRS_STRING_07_007: [ STRING_new_with_memory shall return a NULL STRING_HANDLE if the supplied char* is NULL. ]

STRING_new_quoted

extern STRING_HANDLE STRING_new_quoted(const char*)

SRS_STRING_07_008: [ STRING_new_quoted shall return a valid STRING_HANDLE Copying the supplied const char* value surrounded by quotes. ]

SRS_STRING_07_009: [ STRING_new_quoted shall return a NULL STRING_HANDLE if the supplied const char* is NULL. ]

SRS_STRING_07_031: [ STRING_new_quoted shall return a NULL STRING_HANDLE if any error is encountered. ]

STRING_new_JSON

extern STRING_HANDLE STRING_new_JSON(const char* source);

STRING_new_JSON produces a JSON value representation of the parameter passed as argument source.

SRS_STRING_02_011: [ If source is NULL then STRING_new_JSON shall return NULL. ]

STRING_new_JSON shall produce a STRING_HANDLE according to the following:

SRS_STRING_02_012: [ The string shall begin with the quote character. ]

SRS_STRING_02_013: [ The string shall copy the characters of source "as they are" (until the '\0' character) with the following exceptions: ]

**SRS_STRING_02_014: [** If any character has the value outside [1...127 **]** then STRING_new_JSON shall fail and return NULL.]
**SRS_STRING_02_016: [** If the character is " (quote) then it shall be repsented as \". **]**
**SRS_STRING_02_017: [** If the character is \ (backslash) then it shall represented as \\. **]**
**SRS_STRING_02_018: [** If the character is / (slash) then it shall be represented as \/. **]**
**SRS_STRING_02_019: [** If the character code is less than 0x20 then it shall be represented as \u00xx, where xx is the hex representation of the character code. **]**

SRS_STRING_02_020: [ The string shall end with " (quote). ]

SRS_STRING_02_021: [ If the complete JSON representation cannot be produced, then STRING_new_JSON shall fail and return NULL. ]

STRING_delete

extern void STRING_delete(STRING_HANDLE handle);

SRS_STRING_07_010: [ STRING_delete will free the memory allocated by the STRING_HANDLE. ]

SRS_STRING_07_011: [ STRING_delete will not attempt to free anything with a NULL STRING_HANDLE. ]

STRING_concat

extern int STRING_concat(STRING_HANDLE handle, const char* s2)

SRS_STRING_07_012: [ STRING_concat shall concatenate the given STRING_HANDLE and the const char* value and place the value in the handle. ]

SRS_STRING_07_013: [ STRING_concat shall return a nonzero number if an error is encountered. ]

STRING_concat

extern int STRING_concat(STRING_HANDLE handle, const char* s2)

SRS_STRING_07_034: [ String_Concat_with_STRING shall concatenate a given STRING_HANDLE variable with a source STRING_HANDLE. ]

SRS_STRING_07_035: [ String_Concat_with_STRING shall return a nonzero number if an error is encountered. ]

STRING_quote

extern int STRING_quote(STRING_HANDLE handle)

SRS_STRING_07_014: [ STRING_quote shall "quote" the supplied STRING_HANDLE and return 0 on success. ]

SRS_STRING_07_015: [ STRING_quote shall return a nonzero value if any of the supplied parameters are NULL. ]

SRS_STRING_07_029: [ STRING_quote shall return a nonzero value if any error is encountered. ]

STRING_copy

extern int STRING_copy(STRING_HANDLE s1, const char* s2)

SRS_STRING_07_016: [ STRING_copy shall copy the const char* into the supplied STRING_HANDLE. ]

SRS_STRING_07_017: [ STRING_copy shall return a nonzero value if any of the supplied parameters are NULL. ]

SRS_STRING_07_027: [ STRING_copy shall return a nonzero value if any error is encountered. ]

SRS_STRING_07_026: [ If the underlying char* refered to by s1 handle is equal to char* s2 than STRING_copy shall be a noop and return 0. ]

SRS_STRING_07_033: [ If overlapping pointer address is given to STRING_copy the behavior is undefined. ]

STRING_copy_n

extern int STRING_copy_n(STRING_HANDLE s1, const char* s2, size_t n)

SRS_STRING_07_018: [ STRING_copy_n shall copy the number of characters in const char* or the size_t whichever is lesser. ]

SRS_STRING_07_019: [ STRING_copy_n shall return a nonzero value if STRING_HANDLE or const char* is NULL. ]

SRS_STRING_07_028: [ STRING_copy_n shall return a nonzero value if any error is encountered. ]

STRING_c_str

extern const char* STRING_c_str(STRING_HANDLE handle)

SRS_STRING_07_020: [ STRING_c_str shall return the const char* associated with the given STRING_HANDLE. ]

SRS_STRING_07_021: [ STRING_c_str shall return NULL if the STRING_HANDLE is NULL. ]

STRING_empty

extern int STRING_empty(STRING_HANDLE s1)

SRS_STRING_07_022: [ STRING_empty shall revert the STRING_HANDLE to an empty state. ]

SRS_STRING_07_023: [ STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. ]

SRS_STRING_07_030: [ STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. ]

STRING_length

extern size_t STRING_length(STRING_HANDLE handle)

SRS_STRING_07_024: [ STRING_length shall return the length of the underlying char* for the given handle ]

SRS_STRING_07_025: [ STRING_length shall return zero if the given handle is NULL. ]

STRING_construct_n

extern STRING_HANDLE STRING_construct_n(const char* psz, size_t n);

SRS_STRING_02_007: [ STRING_construct_n shall construct a STRING_HANDLE from first "n" characters of the string pointed to by psz parameter. ]

SRS_STRING_02_008: [ If psz is NULL then STRING_construct_n shall return NULL. ]

SRS_STRING_02_009: [ If n is bigger than the size of the string psz, then STRING_construct_n shall return NULL. ]

SRS_STRING_02_010: [ In all other error cases, STRING_construct_n shall return NULL. ]

STRING_compare

extern int STRING_compare(STRING_HANDLE h1, STRING_HANDLE h2);

SRS_STRING_07_034: [ STRING_compare returns an integer greater than, equal to, or less than zero, accordingly as the string pointed to by s1 is greater than, equal to, or less than the string s2. ]

SRS_STRING_07_035: [ If h1 and h2 are both NULL then STRING_compare shall return 0. ]

SRS_STRING_07_036: [ If h1 is NULL and h2 is a nonNULL value then STRING_compare shall return 1. ]

SRS_STRING_07_037: [ If h2 is NULL and h1 is a nonNULL value then STRING_compare shall return -1. ]

SRS_STRING_07_038: [ STRING_compare shall compare the char s variable using the strcmp function. ]

STRING_from_byte_array

extern STRING_HANDLE STRING_from_byte_array(const unsigned char* source, size_t size)

STRING_from_BUFFER builds a string that has the same content (byte-by-byte) as a byte array.

SRS_STRING_02_022: [ If source is NULL and size > 0 then STRING_from_BUFFER shall fail and return NULL. ]

SRS_STRING_02_023: [ Otherwise, STRING_from_BUFFER shall build a string that has the same content (byte-by-byte) as source and return a non-NULL handle. ]

SRS_STRING_02_024: [ If building the string fails, then STRING_from_BUFFER shall fail and return NULL. ]

STRING_construct_sprintf

extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);

STRING_construct_sprintf constructs the STRING_HANDLE from a printf formatting

SRS_STRING_07_039: [ If the parameter format is NULL then STRING_construct_sprintf shall return NULL. ]

SRS_STRING_07_040: [ If any error is encountered STRING_construct_sprintf shall return NULL. ]

SRS_STRING_07_041: [ STRING_construct_sprintf shall determine the size of the resulting string and allocate the necessary memory. ]

SRS_STRING_07_045: [ STRING_construct_sprintf shall allocate a new string with the value of the specified printf formated const char. ]

STRING_sprintf

extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);

STRING_sprintf shall append a printf format style string to the end of a STRING_HANDLE.

SRS_STRING_07_042: [ if the parameters s1 or format are NULL then STRING_sprintf shall return non zero value. ]

SRS_STRING_07_043: [ If any error is encountered STRING_sprintf shall return a non zero value. ]

SRS_STRING_07_044: [ On success STRING_sprintf shall return 0. ]

STRING_replace

int STRING_replace(STRING_HANDLE handle, char target, char replace)

SRS_STRING_07_046: [ If handle is NULL STRING_replace shall return a non-zero value. ]

SRS_STRING_07_047: [ STRING_replace shall replace all instances of target with replace. ]

SRS_STRING_07_048: [ If target and replace are equal STRING_replace, shall do nothing shall return zero. ]

SRS_STRING_07_049: [ On success STRING_replace shall return zero. ]