V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
v8::String Class Reference

#include <v8.h>

Inheritance diagram for v8::String:
v8::Name v8::Primitive v8::Value v8::Data

Classes

class  ExternalOneByteStringResource
 
class  ExternalStringResource
 
class  ExternalStringResourceBase
 
class  Utf8Value
 
class  Value
 

Public Types

enum  Encoding { UNKNOWN_ENCODING = 0x1, TWO_BYTE_ENCODING = 0x0, ONE_BYTE_ENCODING = 0x8 }
 
enum  WriteOptions {
  NO_OPTIONS = 0, HINT_MANY_WRITES_EXPECTED = 1, NO_NULL_TERMINATION = 2, PRESERVE_ONE_BYTE_NULL = 4,
  REPLACE_INVALID_UTF8 = 8
}
 
enum  NewStringType { kNormalString = static_cast<int>(v8::NewStringType::kNormal), kInternalizedString = static_cast<int>(v8::NewStringType::kInternalized) }
 

Public Member Functions

int Length () const
 
int Utf8Length (Isolate *isolate) const
 
bool IsOneByte () const
 
bool ContainsOnlyOneByte () const
 
int Write (Isolate *isolate, uint16_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
 
int WriteOneByte (Isolate *isolate, uint8_t *buffer, int start=0, int length=-1, int options=NO_OPTIONS) const
 
int WriteUtf8 (Isolate *isolate, char *buffer, int length=-1, int *nchars_ref=nullptr, int options=NO_OPTIONS) const
 
bool IsExternal () const
 
bool IsExternalOneByte () const
 
V8_INLINE ExternalStringResourceBaseGetExternalStringResourceBase (Encoding *encoding_out) const
 
V8_INLINE ExternalStringResourceGetExternalStringResource () const
 
const ExternalOneByteStringResourceGetExternalOneByteStringResource () const
 
bool MakeExternal (ExternalStringResource *resource)
 
bool MakeExternal (ExternalOneByteStringResource *resource)
 
bool CanMakeExternal ()
 
bool StringEquals (Local< String > str)
 
- Public Member Functions inherited from v8::Name
int GetIdentityHash ()
 
- Public Member Functions inherited from v8::Value
V8_INLINE bool IsUndefined () const
 
V8_INLINE bool IsNull () const
 
V8_INLINE bool IsNullOrUndefined () const
 
bool IsTrue () const
 
bool IsFalse () const
 
bool IsName () const
 
V8_INLINE bool IsString () const
 
bool IsSymbol () const
 
bool IsFunction () const
 
bool IsArray () const
 
bool IsObject () const
 
bool IsBigInt () const
 
bool IsBoolean () const
 
bool IsNumber () const
 
bool IsExternal () const
 
bool IsInt32 () const
 
bool IsUint32 () const
 
bool IsDate () const
 
bool IsArgumentsObject () const
 
bool IsBigIntObject () const
 
bool IsBooleanObject () const
 
bool IsNumberObject () const
 
bool IsStringObject () const
 
bool IsSymbolObject () const
 
bool IsNativeError () const
 
bool IsRegExp () const
 
bool IsAsyncFunction () const
 
bool IsGeneratorFunction () const
 
bool IsGeneratorObject () const
 
bool IsPromise () const
 
bool IsMap () const
 
bool IsSet () const
 
bool IsMapIterator () const
 
bool IsSetIterator () const
 
bool IsWeakMap () const
 
bool IsWeakSet () const
 
bool IsArrayBuffer () const
 
bool IsArrayBufferView () const
 
bool IsTypedArray () const
 
bool IsUint8Array () const
 
bool IsUint8ClampedArray () const
 
bool IsInt8Array () const
 
bool IsUint16Array () const
 
bool IsInt16Array () const
 
bool IsUint32Array () const
 
bool IsInt32Array () const
 
bool IsFloat32Array () const
 
bool IsFloat64Array () const
 
bool IsBigInt64Array () const
 
bool IsBigUint64Array () const
 
bool IsDataView () const
 
bool IsSharedArrayBuffer () const
 
bool IsProxy () const
 
bool IsWebAssemblyCompiledModule () const
 
bool IsModuleNamespaceObject () const
 
V8_WARN_UNUSED_RESULT MaybeLocal< BigIntToBigInt (Local< Context > context) const
 
 V8_DEPRECATE_SOON ("ToBoolean can never throw. Use Local version.", V8_WARN_UNUSED_RESULT MaybeLocal< Boolean > ToBoolean(Local< Context > context) const)
 
V8_WARN_UNUSED_RESULT MaybeLocal< NumberToNumber (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< StringToString (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< StringToDetailString (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< ObjectToObject (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< IntegerToInteger (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< Uint32ToUint32 (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT MaybeLocal< Int32ToInt32 (Local< Context > context) const
 
Local< BooleanToBoolean (Isolate *isolate) const
 
 V8_DEPRECATE_SOON ("Use maybe version", Local< Number > ToNumber(Isolate *isolate) const)
 
 V8_DEPRECATE_SOON ("Use maybe version", Local< String > ToString(Isolate *isolate) const)
 
 V8_DEPRECATE_SOON ("Use maybe version", Local< Object > ToObject(Isolate *isolate) const)
 
 V8_DEPRECATE_SOON ("Use maybe version", Local< Integer > ToInteger(Isolate *isolate) const)
 
 V8_DEPRECATE_SOON ("Use maybe version", Local< Int32 > ToInt32(Isolate *isolate) const)
 
V8_WARN_UNUSED_RESULT MaybeLocal< Uint32ToArrayIndex (Local< Context > context) const
 
bool BooleanValue (Isolate *isolate) const
 
 V8_DEPRECATE_SOON ("BooleanValue can never throw. Use Isolate version.", V8_WARN_UNUSED_RESULT Maybe< bool > BooleanValue(Local< Context > context) const)
 
V8_WARN_UNUSED_RESULT Maybe< double > NumberValue (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT Maybe< int64_tIntegerValue (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT Maybe< uint32_tUint32Value (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT Maybe< int32_t > Int32Value (Local< Context > context) const
 
V8_WARN_UNUSED_RESULT Maybe< boolEquals (Local< Context > context, Local< Value > that) const
 
bool StrictEquals (Local< Value > that) const
 
bool SameValue (Local< Value > that) const
 
Local< StringTypeOf (Isolate *)
 
Maybe< boolInstanceOf (Local< Context > context, Local< Object > object)
 

Static Public Member Functions

static V8_INLINE Local< StringEmpty (Isolate *isolate)
 
static V8_INLINE StringCast (v8::Value *obj)
 
static V8_DEPRECATE_SOON ("Use maybe version", Local< String > NewFromUtf8(Isolate *isolate, const char *data, NewStringType type=kNormalString, int length=-1))
 
static V8_WARN_UNUSED_RESULT MaybeLocal< StringNewFromUtf8 (Isolate *isolate, const char *data, v8::NewStringType type, int length=-1)
 
static V8_WARN_UNUSED_RESULT MaybeLocal< StringNewFromOneByte (Isolate *isolate, const uint8_t *data, v8::NewStringType type, int length=-1)
 
static V8_DEPRECATE_SOON ("Use maybe version", Local< String > NewFromTwoByte(Isolate *isolate, const uint16_t *data, NewStringType type=kNormalString, int length=-1))
 
static V8_WARN_UNUSED_RESULT MaybeLocal< StringNewFromTwoByte (Isolate *isolate, const uint16_t *data, v8::NewStringType type, int length=-1)
 
static Local< StringConcat (Isolate *isolate, Local< String > left, Local< String > right)
 
static V8_WARN_UNUSED_RESULT MaybeLocal< StringNewExternalTwoByte (Isolate *isolate, ExternalStringResource *resource)
 
static V8_DEPRECATE_SOON ("Use maybe version", Local< String > NewExternal(Isolate *isolate, ExternalOneByteStringResource *resource))
 
static V8_WARN_UNUSED_RESULT MaybeLocal< StringNewExternalOneByte (Isolate *isolate, ExternalOneByteStringResource *resource)
 
- Static Public Member Functions inherited from v8::Name
static V8_INLINE NameCast (Value *obj)
 
- Static Public Member Functions inherited from v8::Value
template<class T >
static V8_INLINE ValueCast (T *value)
 

Static Public Attributes

static constexpr int kMaxLength
 

Detailed Description

A JavaScript string value (ECMA-262, 4.3.17).

Definition at line 2537 of file v8.h.

Member Enumeration Documentation

◆ WriteOptions

Write the contents of the string to an external buffer. If no arguments are given, expects the buffer to be large enough to hold the entire string and NULL terminator. Copies the contents of the string and the NULL terminator into the buffer.

WriteUtf8 will not write partial UTF-8 sequences, preferring to stop before the end of the buffer.

Copies up to length characters into the output buffer. Only null-terminates if there is enough space in the buffer.

Parameters
bufferThe buffer into which the string will be copied.
startThe starting position within the string at which copying begins.
lengthThe number of characters to copy from the string. For WriteUtf8 the number of bytes in the buffer.
nchars_refThe number of characters written, can be NULL.
optionsVarious options that might affect performance of this or subsequent operations.
Returns
The number of characters copied to the buffer excluding the null terminator. For WriteUtf8: The number of bytes copied to the buffer including the null terminator (if written).

Definition at line 2599 of file v8.h.

Member Function Documentation

◆ CanMakeExternal()

bool v8::String::CanMakeExternal ( )

Returns true if this string can be made external.

Definition at line 6678 of file api.cc.

◆ Concat()

Local< String > v8::String::Concat ( Isolate *  isolate,
Local< String left,
Local< String right 
)
static

Creates a new string by concatenating the left and the right strings passed in as parameters.

Definition at line 6552 of file api.cc.

◆ ContainsOnlyOneByte()

bool v8::String::ContainsOnlyOneByte ( ) const

Returns whether this string contain only one byte data, i.e. ISO-8859-1 code points. Will read the entire string in some cases.

Definition at line 5294 of file api.cc.

◆ Empty()

Local< String > v8::String::Empty ( Isolate *  isolate)
static

A zero length string.

Definition at line 9913 of file v8.h.

◆ GetExternalOneByteStringResource()

const v8::String::ExternalOneByteStringResource * v8::String::GetExternalOneByteStringResource ( ) const

Get the ExternalOneByteStringResource for an external one-byte string. Returns NULL if IsExternalOneByte() doesn't return true.

Definition at line 5703 of file api.cc.

◆ GetExternalStringResource()

String::ExternalStringResource * v8::String::GetExternalStringResource ( ) const

Get the ExternalStringResource for an external string. Returns NULL if IsExternal() doesn't return true.

Definition at line 9922 of file v8.h.

◆ GetExternalStringResourceBase()

String::ExternalStringResourceBase * v8::String::GetExternalStringResourceBase ( String::Encoding *  encoding_out) const

If the string is an external string, return the ExternalStringResourceBase regardless of the encoding, otherwise return NULL. The encoding of the string is returned in encoding_out.

Definition at line 9941 of file v8.h.

◆ IsExternal()

bool v8::String::IsExternal ( ) const

Returns true if the string is external

Definition at line 5605 of file api.cc.

◆ IsExternalOneByte()

bool v8::String::IsExternalOneByte ( ) const

Returns true if the string is both external and one-byte.

Definition at line 5611 of file api.cc.

◆ IsOneByte()

bool v8::String::IsOneByte ( ) const

Returns whether this string is known to contain only one byte data, i.e. ISO-8859-1 code points. Does not read the string. False negatives are possible.

Definition at line 5181 of file api.cc.

◆ Length()

int v8::String::Length ( ) const

Returns the number of characters (UTF-16 code units) in this string.

Definition at line 5175 of file api.cc.

◆ MakeExternal() [1/2]

bool v8::String::MakeExternal ( ExternalStringResource resource)

Associate an external string resource with this string by transforming it in place so that existing references to this string in the JavaScript heap will use the external string resource. The external string resource's character contents need to be equivalent to this string. Returns true if the string has been changed to be an external string. The string is not modified if the operation fails. See NewExternal for information on the lifetime of the resource.

Definition at line 6621 of file api.cc.

◆ MakeExternal() [2/2]

bool v8::String::MakeExternal ( ExternalOneByteStringResource resource)

Associate an external string resource with this string by transforming it in place so that existing references to this string in the JavaScript heap will use the external string resource. The external string resource's character contents need to be equivalent to this string. Returns true if the string has been changed to be an external string. The string is not modified if the operation fails. See NewExternal for information on the lifetime of the resource.

Definition at line 6649 of file api.cc.

◆ NewExternalTwoByte()

MaybeLocal< String > v8::String::NewExternalTwoByte ( Isolate *  isolate,
ExternalStringResource resource 
)
static

Creates a new external string using the data defined in the given resource. When the external string is no longer live on V8's heap the resource will be disposed by calling its Dispose method. The caller of this function should not otherwise delete or modify the resource. Neither should the underlying buffer be deallocated or modified except through the destructor of the external string resource.

Definition at line 6569 of file api.cc.

◆ NewFromOneByte()

MaybeLocal< String > v8::String::NewFromOneByte ( Isolate *  isolate,
const uint8_t *  data,
v8::NewStringType  type,
int  length = -1 
)
static

Allocates a new string from Latin-1 data. Only returns an empty value when length > kMaxLength.

Definition at line 6528 of file api.cc.

◆ NewFromTwoByte()

MaybeLocal< String > v8::String::NewFromTwoByte ( Isolate *  isolate,
const uint16_t *  data,
v8::NewStringType  type,
int  length = -1 
)
static

Allocates a new string from UTF-16 data. Only returns an empty value when length > kMaxLength.

Definition at line 6535 of file api.cc.

◆ NewFromUtf8()

MaybeLocal< String > v8::String::NewFromUtf8 ( Isolate *  isolate,
const char data,
v8::NewStringType  type,
int  length = -1 
)
static

Allocates a new string from UTF-8 data. Only returns an empty value when length > kMaxLength.

Definition at line 6511 of file api.cc.

◆ StringEquals()

bool v8::String::StringEquals ( Local< String str)

Returns true if the strings values are equal. Same as JS ==/===.

Definition at line 6694 of file api.cc.

◆ Utf8Length()

int v8::String::Utf8Length ( Isolate *  isolate) const

Returns the number of bytes in the UTF-8 encoded representation of this string.

Definition at line 5301 of file api.cc.

◆ V8_DEPRECATE_SOON() [1/3]

static v8::String::V8_DEPRECATE_SOON ( "Use maybe version"  ,
Local< String >   NewFromUtf8Isolate *isolate, const char *data, NewStringType type=kNormalString, int length=-1 
)
static

Allocates a new string from UTF-8 data.

◆ V8_DEPRECATE_SOON() [2/3]

static v8::String::V8_DEPRECATE_SOON ( "Use maybe version"  ,
Local< String >   NewFromTwoByteIsolate *isolate, const uint16_t *data, NewStringType type=kNormalString, int length=-1 
)
static

Allocates a new string from UTF-16 data.

◆ V8_DEPRECATE_SOON() [3/3]

static v8::String::V8_DEPRECATE_SOON ( "Use maybe version"  ,
Local< String >   NewExternalIsolate *isolate, ExternalOneByteStringResource *resource 
)
static

Creates a new external string using the one-byte data defined in the given resource. When the external string is no longer live on V8's heap the resource will be disposed by calling its Dispose method. The caller of this function should not otherwise delete or modify the resource. Neither should the underlying buffer be deallocated or modified except through the destructor of the external string resource.

Member Data Documentation

◆ kMaxLength

constexpr int v8::String::kMaxLength
static
Initial value:
= internal::kApiTaggedSize == 4
? (1 << 28) - 16
: internal::kSmiMaxValue / 2 - 24

Definition at line 2539 of file v8.h.


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