#include <v8-primitive.h>

Inheritance diagram for String:

[legend]

Collaboration diagram for String:

[legend]

Data Structures
class	ExternalOneByteStringResource

class	ExternalStringResource

class	ExternalStringResourceBase

class	Utf8Value

class	Value

class	ValueView

struct	WriteFlags

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 }

Public Member Functions
int	Length () const

int	Utf8Length (Isolate *isolate) const

size_t	Utf8LengthV2 (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

void	WriteV2 (Isolate isolate, uint32_t offset, uint32_t length, uint16_t buffer, int flags=WriteFlags::kNone) const

void	WriteOneByteV2 (Isolate isolate, uint32_t offset, uint32_t length, uint8_t buffer, int flags=WriteFlags::kNone) const

size_t	WriteUtf8V2 (Isolate isolate, char buffer, size_t capacity, int flags=WriteFlags::kNone, size_t *processed_characters_return=nullptr) const

bool	IsExternal () const

bool	IsExternalTwoByte () const

bool	IsExternalOneByte () const

Local< String >	InternalizeString (Isolate *isolate)

V8_INLINE ExternalStringResourceBase *	GetExternalStringResourceBase (v8::Isolate isolate, Encoding encoding_out) const

V8_INLINE ExternalStringResourceBase *	GetExternalStringResourceBase (Encoding *encoding_out) const

V8_INLINE ExternalStringResource *	GetExternalStringResource () const

const ExternalOneByteStringResource *	GetExternalOneByteStringResource () const

bool	MakeExternal (ExternalStringResource *resource)

bool	MakeExternal (Isolate isolate, ExternalStringResource resource)

bool	MakeExternal (ExternalOneByteStringResource *resource)

bool	MakeExternal (Isolate isolate, ExternalOneByteStringResource resource)

bool	CanMakeExternal (Encoding encoding) const

bool	StringEquals (Local< String > str) const

template<>
V8_WARN_UNUSED_RESULT Local< String >	NewFromUtf8Literal (Isolate *isolate, const char(&literal)[1], NewStringType type)

Public Member Functions inherited from Name
int	GetIdentityHash ()

Public Member Functions inherited from Value
V8_INLINE bool	IsUndefined () const

V8_INLINE bool	IsNull () const

V8_INLINE bool	IsNullOrUndefined () const

V8_INLINE bool	IsTrue () const

V8_INLINE 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	IsWeakRef () 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	IsFloat16Array () const

bool	IsFloat32Array () const

bool	IsFloat64Array () const

bool	IsBigInt64Array () const

bool	IsBigUint64Array () const

bool	IsDataView () const

bool	IsSharedArrayBuffer () const

bool	IsProxy () const

bool	IsWasmMemoryObject () const

bool	IsWasmMemoryMapDescriptor () const

bool	IsWasmModuleObject () const

bool	IsWasmNull () const

bool	IsModuleNamespaceObject () const

bool	IsPrimitive () const

V8_WARN_UNUSED_RESULT MaybeLocal< Primitive >	ToPrimitive (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Numeric >	ToNumeric (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< BigInt >	ToBigInt (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Number >	ToNumber (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< String >	ToString (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< String >	ToDetailString (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Object >	ToObject (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Integer >	ToInteger (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Uint32 >	ToUint32 (Local< Context > context) const

V8_WARN_UNUSED_RESULT MaybeLocal< Int32 >	ToInt32 (Local< Context > context) const

Local< Boolean >	ToBoolean (Isolate *isolate) const

V8_WARN_UNUSED_RESULT MaybeLocal< Uint32 >	ToArrayIndex (Local< Context > context) const

bool	BooleanValue (Isolate *isolate) const

V8_WARN_UNUSED_RESULT Maybe< double >	NumberValue (Local< Context > context) const

V8_WARN_UNUSED_RESULT Maybe< int64_t >	IntegerValue (Local< Context > context) const

V8_WARN_UNUSED_RESULT Maybe< uint32_t >	Uint32Value (Local< Context > context) const

V8_WARN_UNUSED_RESULT Maybe< int32_t >	Int32Value (Local< Context > context) const

V8_WARN_UNUSED_RESULT Maybe< bool >	Equals (Local< Context > context, Local< Value > that) const

bool	StrictEquals (Local< Value > that) const

bool	SameValue (Local< Value > that) const

Local< String >	TypeOf (Isolate *)

Maybe< bool >	InstanceOf (Local< Context > context, Local< Object > object)

uint32_t	GetHash ()

template<>
V8_INLINE Value *	Cast (Data *value)

Public Member Functions inherited from Data
bool	IsValue () const

bool	IsModule () const

bool	IsModuleRequest () const

bool	IsFixedArray () const

bool	IsPrivate () const

bool	IsObjectTemplate () const

bool	IsFunctionTemplate () const

bool	IsContext () const

Static Public Member Functions
static V8_INLINE Local< String >	Empty (Isolate *isolate)

static V8_INLINE String *	Cast (v8::Data *data)

template<int N>
static V8_WARN_UNUSED_RESULT Local< String >	NewFromUtf8Literal (Isolate *isolate, const char(&literal)[N], NewStringType type=NewStringType::kNormal)

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

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

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

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

static V8_WARN_UNUSED_RESULT MaybeLocal< String >	NewExternalTwoByte (Isolate isolate, ExternalStringResource resource)

static V8_WARN_UNUSED_RESULT MaybeLocal< String >	NewExternalOneByte (Isolate isolate, ExternalOneByteStringResource resource)

Static Public Member Functions inherited from Name
static V8_INLINE Name *	Cast (Data *data)

Static Public Member Functions inherited from Value
template<class T>
static V8_INLINE Value *	Cast (T *value)

Static Public Attributes
static constexpr int	kMaxLength

Detailed Description

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

Definition at line 124 of file v8-primitive.h.

Member Enumeration Documentation

◆ Encoding

enum Encoding

Enumerator
UNKNOWN_ENCODING
TWO_BYTE_ENCODING
ONE_BYTE_ENCODING

Definition at line 129 of file v8-primitive.h.

◆ WriteOptions

enum 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

buffer	The buffer into which the string will be copied.
start	The starting position within the string at which copying begins.
length	The number of characters to copy from the string. For WriteUtf8 the number of bytes in the buffer.
nchars_ref	The number of characters written, can be NULL.
options	Various 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).

Enumerator
NO_OPTIONS
HINT_MANY_WRITES_EXPECTED
NO_NULL_TERMINATION
PRESERVE_ONE_BYTE_NULL
REPLACE_INVALID_UTF8

Definition at line 191 of file v8-primitive.h.

Member Function Documentation

◆ CanMakeExternal()

bool CanMakeExternal ( Encoding encoding ) const

Returns true if this string can be made external, given the encoding for the external string resource.

References CanMakeExternal().

Referenced by CanMakeExternal().

◆ Cast()

static V8_INLINE String * Cast ( v8::Data * data )

inlinestatic

Definition at line 509 of file v8-primitive.h.

References V8_INLINE.

◆ Concat()

static Local< 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.

◆ ContainsOnlyOneByte()

bool 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.

References ContainsOnlyOneByte().

Referenced by ContainsOnlyOneByte().

◆ Empty()

Local< String > Empty ( Isolate * isolate )

static

A zero length string.

Definition at line 980 of file v8-primitive.h.

Referenced by NewFromUtf8Literal(), and WriteUtf8V2().

◆ GetExternalOneByteStringResource()

const ExternalOneByteStringResource * GetExternalOneByteStringResource ( ) const

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

◆ GetExternalStringResource()

String::ExternalStringResource * GetExternalStringResource ( ) const

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

Definition at line 988 of file v8-primitive.h.

References ValueHelper::ValueAsAddress().

◆ GetExternalStringResourceBase() [1/2]

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

Definition at line 1030 of file v8-primitive.h.

References ValueHelper::ValueAsAddress().

◆ GetExternalStringResourceBase() [2/2]

String::ExternalStringResourceBase * GetExternalStringResourceBase	(	v8::Isolate *	isolate,
		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 1008 of file v8-primitive.h.

References ValueHelper::ValueAsAddress().

◆ InternalizeString()

Local< String > InternalizeString ( Isolate * isolate )

Returns the internalized string. See NewStringType::kInternalized for details on internalized strings.

◆ IsExternal()

bool IsExternal ( ) const

Returns true if the string is external.

◆ IsExternalOneByte()

bool IsExternalOneByte ( ) const

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

◆ IsExternalTwoByte()

bool IsExternalTwoByte ( ) const

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

◆ IsOneByte()

bool 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.

References IsOneByte().

Referenced by IsOneByte().

◆ Length()

int Length ( ) const

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

◆ MakeExternal() [1/4]

bool 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.

References MakeExternal().

◆ MakeExternal() [2/4]

bool 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.

References MakeExternal().

Referenced by MakeExternal(), MakeExternal(), MakeExternal(), and MakeExternal().

◆ MakeExternal() [3/4]

bool MakeExternal	(	Isolate *	isolate,
		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.

References MakeExternal().

◆ MakeExternal() [4/4]

bool MakeExternal	(	Isolate *	isolate,
		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.

References MakeExternal().

◆ NewExternalOneByte()

static V8_WARN_UNUSED_RESULT MaybeLocal< String > NewExternalOneByte	(	Isolate *	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.

References NewExternalOneByte(), v8::V8_DEPRECATE_SOON(), and V8_WARN_UNUSED_RESULT.

Referenced by NewExternalOneByte().

◆ NewExternalTwoByte()

static V8_WARN_UNUSED_RESULT MaybeLocal< 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.

References V8_WARN_UNUSED_RESULT.

◆ NewFromOneByte()

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

static

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

References v8::kNormal, and V8_WARN_UNUSED_RESULT.

◆ NewFromTwoByte()

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

static

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

References v8::kNormal, and V8_WARN_UNUSED_RESULT.

◆ NewFromUtf8()

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

static

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

References v8::kNormal, and V8_WARN_UNUSED_RESULT.

Referenced by Template::Set().

◆ NewFromUtf8Literal() [1/2]

template<>

V8_WARN_UNUSED_RESULT Local< String > NewFromUtf8Literal	(	Isolate *	isolate,
		const char(&)	literal[1],
		NewStringType	type )

inline

Definition at line 763 of file v8-primitive.h.

References Empty(), and V8_WARN_UNUSED_RESULT.

◆ NewFromUtf8Literal() [2/2]

template<int N>

static V8_WARN_UNUSED_RESULT Local< String > NewFromUtf8Literal	(	Isolate *	isolate,
		const char(&)	literal[N],
		NewStringType	type = NewStringType::kNormal )

inlinestatic

Allocates a new string from a UTF-8 literal. This is equivalent to calling String::NewFromUtf(isolate, "...").ToLocalChecked(), but without the check overhead.

When called on a string literal containing '\0', the inferred length is the length of the input array minus 1 (for the final '\0') and not the value returned by strlen.

Definition at line 526 of file v8-primitive.h.

References kMaxLength, v8::kNormal, NewFromUtf8Literal(), and V8_WARN_UNUSED_RESULT.

Referenced by NewFromUtf8Literal(), and Isolate::ThrowError().

◆ StringEquals()

bool StringEquals ( Local< String > str ) const

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

References StringEquals().

Referenced by StringEquals().

◆ Utf8Length()

int Utf8Length ( Isolate * isolate ) const

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

References Utf8Length().

Referenced by Utf8Length().

◆ Utf8LengthV2()

size_t Utf8LengthV2 ( Isolate * isolate ) const

Returns the number of bytes needed for the Utf8 encoding of this string.

References Utf8LengthV2().

Referenced by Utf8LengthV2().

◆ Write()

int Write	(	Isolate *	isolate,
		uint16_t *	buffer,
		int	start = 0,
		int	length = -1,
		int	options = NO_OPTIONS ) const

References NO_OPTIONS, V8_DEPRECATED, and Write().

Referenced by Write().

◆ WriteOneByte()

int WriteOneByte	(	Isolate *	isolate,
		uint8_t *	buffer,
		int	start = 0,
		int	length = -1,
		int	options = NO_OPTIONS ) const

References NO_OPTIONS, V8_DEPRECATED, and WriteOneByte().

Referenced by WriteOneByte().

◆ WriteOneByteV2()

void WriteOneByteV2	(	Isolate *	isolate,
		uint32_t	offset,
		uint32_t	length,
		uint8_t *	buffer,
		int	flags = WriteFlags::kNone ) const

References String::WriteFlags::kNone.

◆ WriteUtf8()

int WriteUtf8	(	Isolate *	isolate,
		char *	buffer,
		int	length = -1,
		int *	nchars_ref = nullptr,
		int	options = NO_OPTIONS ) const

References NO_OPTIONS, and WriteUtf8().

Referenced by WriteUtf8().

◆ WriteUtf8V2()

size_t WriteUtf8V2	(	Isolate *	isolate,
		char *	buffer,
		size_t	capacity,
		int	flags = WriteFlags::kNone,
		size_t *	processed_characters_return = nullptr ) const

Encode the contents of the string as Utf8 into an external buffer.

Encodes the characters of this string as Utf8 and writes them into the output buffer until either all characters were encoded or the buffer is full. Will not write partial UTF-8 sequences, preferring to stop before the end of the buffer. If null termination is requested, the output buffer will always be null terminated even if not all characters fit. In that case, the capacity must be at least one. The required size of the output buffer can be determined using Utf8Length().

Parameters

buffer	The buffer into which the string will be written.
capacity	The number of bytes available in the output buffer.
flags	Various flags that influence the behavior of this operation.
processed_characters_return	The number of processed characters from the buffer.

Returns: The number of bytes copied to the buffer including the null terminator (if written).

References Empty(), String::WriteFlags::kNone, and V8_INLINE.

◆ WriteV2()

void WriteV2	(	Isolate *	isolate,
		uint32_t	offset,
		uint32_t	length,
		uint16_t *	buffer,
		int	flags = WriteFlags::kNone ) const

Write the contents of the string to an external buffer.

Copies length characters into the output buffer starting at offset. The output buffer must have sufficient space for all characters and the null terminator if null termination is requested through the flags.

Parameters

offset	The position within the string at which copying begins.
length	The number of characters to copy from the string.
buffer	The buffer into which the string will be copied.
flags	Various flags that influence the behavior of this operation.

References String::WriteFlags::kNone.

Field Documentation

◆ kMaxLength

int kMaxLength

staticconstexpr

Initial value:

=

internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24

v8::internal::kApiSystemPointerSize

const int kApiSystemPointerSize

Definition v8-internal.h:65

Definition at line 126 of file v8-primitive.h.

Referenced by NewFromUtf8Literal().

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

include/v8-primitive.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Encoding

◆ WriteOptions

Member Function Documentation

◆ CanMakeExternal()

◆ Cast()

◆ Concat()

◆ ContainsOnlyOneByte()

◆ Empty()

◆ GetExternalOneByteStringResource()

◆ GetExternalStringResource()

◆ GetExternalStringResourceBase() [1/2]

◆ GetExternalStringResourceBase() [2/2]

◆ InternalizeString()

◆ IsExternal()

◆ IsExternalOneByte()

◆ IsExternalTwoByte()

◆ IsOneByte()

◆ Length()

◆ MakeExternal() [1/4]

◆ MakeExternal() [2/4]

◆ MakeExternal() [3/4]

◆ MakeExternal() [4/4]

◆ NewExternalOneByte()

◆ NewExternalTwoByte()

◆ NewFromOneByte()

◆ NewFromTwoByte()

◆ NewFromUtf8()

◆ NewFromUtf8Literal() [1/2]

◆ NewFromUtf8Literal() [2/2]

◆ StringEquals()

◆ Utf8Length()

◆ Utf8LengthV2()

◆ Write()

◆ WriteOneByte()

◆ WriteOneByteV2()

◆ WriteUtf8()

◆ WriteUtf8V2()

◆ WriteV2()

Field Documentation

◆ kMaxLength