mjs_string_public.h

/*
 * Copyright (c) 2016 Cesanta Software Limited
 * All rights reserved
 */
 
#ifndef MJS_STRING_PUBLIC_H_
#define MJS_STRING_PUBLIC_H_
 
#include "mjs_core_public.h"
 
#define MJS_STRING_LITERAL_MAX_LEN 128
 
#if defined(__cplusplus)
extern "C" {
#endif /* __cplusplus */
 
/*
 * Creates a string primitive value.
 * `str` must point to the utf8 string of length `len`.
 * If `len` is ~0, `str` is assumed to be NUL-terminated and `strlen(str)` is
 * used.
 *
 * If `copy` is non-zero, the string data is copied and owned by the GC. The
 * caller can free the string data afterwards. Otherwise (`copy` is zero), the
 * caller owns the string data, and is responsible for not freeing it while it
 * is used.
 */
mjs_val_t mjs_mk_string(struct mjs* mjs, const char* str, size_t len, int copy);
 
/* Returns true if given value is a primitive string value */
int mjs_is_string(mjs_val_t v);
 
/*
 * Returns a pointer to the string stored in `mjs_val_t`.
 *
 * String length returned in `len`, which is allowed to be NULL. Returns NULL
 * if the value is not a string.
 *
 * JS strings can contain embedded NUL chars and may or may not be NUL
 * terminated.
 *
 * CAUTION: creating new JavaScript object, array, or string may kick in a
 * garbage collector, which in turn may relocate string data and invalidate
 * pointer returned by `mjs_get_string()`.
 *
 * Short JS strings are embedded inside the `mjs_val_t` value itself. This
 * is why a pointer to a `mjs_val_t` is required. It also means that the string
 * data will become invalid once that `mjs_val_t` value goes out of scope.
 */
const char* mjs_get_string(struct mjs* mjs, mjs_val_t* v, size_t* len);
 
/*
 * Returns a pointer to the string stored in `mjs_val_t`.
 *
 * Returns NULL if the value is not a string or if the string is not compatible
 * with a C string.
 *
 * C compatible strings contain exactly one NUL char, in terminal position.
 *
 * All strings owned by the MJS engine (see `mjs_mk_string()`) are guaranteed to
 * be NUL terminated. Out of these, those that don't include embedded NUL chars
 * are guaranteed to be C compatible.
 */
const char* mjs_get_cstring(struct mjs* mjs, mjs_val_t* v);
 
/*
 * Returns the standard strcmp comparison code after comparing a JS string a
 * with a possibly non null-terminated string b. NOTE: the strings are equal
 * only if their length is equal, i.e. the len field doesn't imply strncmp
 * behaviour.
 */
int mjs_strcmp(struct mjs* mjs, mjs_val_t* a, const char* b, size_t len);
 
#if defined(__cplusplus)
}
#endif /* __cplusplus */
 
#endif /* MJS_STRING_PUBLIC_H_ */