0
# Data Types and Performance
1

2
Truffle provides specialized data types and performance optimization features for high-performance language implementations. This includes efficient string handling, profiling utilities, exception management, and performance-oriented data structures.
3

4
## Capabilities
5

6
### String System
7

8
High-performance string implementation with encoding support and lazy operations.
9

10
```java { .api }
11
/**
12
 * Base class for Truffle string implementations
13
 */
14
public abstract class AbstractTruffleString {
15
    
16
    /**
17
     * Get string length in code points
18
     * @param encoding String encoding
19
     * @return Length in code points
20
     */
21
    public abstract int codePointLengthUncached(Encoding encoding);
22
    
23
    /**
24
     * Get string length in bytes
25
     * @param encoding String encoding
26
     * @return Length in bytes
27
     */
28
    public abstract int byteLength(Encoding encoding);
29
    
30
    /**
31
     * Check if string is valid for encoding
32
     * @param encoding Target encoding
33
     * @return true if valid
34
     */
35
    public abstract boolean isValidUncached(Encoding encoding);
36
    
37
    /**
38
     * Switch to different encoding
39
     * @param encoding Target encoding
40
     * @return String in new encoding
41
     */
42
    public abstract TruffleString switchEncodingUncached(Encoding encoding);
43
}
44

45
/**
46
 * Immutable string implementation for Truffle languages
47
 */
48
public final class TruffleString extends AbstractTruffleString {
49
    
50
    /**
51
     * Create TruffleString from Java string
52
     * @param javaString Source Java string
53
     * @param encoding Target encoding
54
     * @return TruffleString instance
55
     */
56
    public static TruffleString fromJavaStringUncached(String javaString, Encoding encoding) {
57
        return null; // Implementation details
58
    }
59
    
60
    /**
61
     * Create TruffleString from byte array
62
     * @param bytes Source bytes
63
     * @param offset Byte offset
64
     * @param length Byte length
65
     * @param encoding Source encoding
66
     * @param copy Whether to copy bytes
67
     * @return TruffleString instance
68
     */
69
    public static TruffleString fromByteArrayUncached(byte[] bytes, int offset, int length, 
70
                                                     Encoding encoding, boolean copy) {
71
        return null; // Implementation details
72
    }
73
    
74
    /**
75
     * Create TruffleString from code point array
76
     * @param codePoints Source code points
77
     * @param offset Code point offset
78
     * @param length Code point length
79
     * @param encoding Target encoding
80
     * @param copy Whether to copy array
81
     * @return TruffleString instance
82
     */
83
    public static TruffleString fromCodePointArrayUncached(int[] codePoints, int offset, int length,
84
                                                          Encoding encoding, boolean copy) {
85
        return null; // Implementation details
86
    }
87
    
88
    /**
89
     * Convert to Java string
90
     * @return Java String
91
     */
92
    public String toJavaStringUncached() {
93
        return null; // Implementation details
94
    }
95
    
96
    /**
97
     * Get hash code for specific encoding
98
     * @param encoding String encoding
99
     * @return Hash code
100
     */
101
    public int hashCodeUncached(Encoding encoding) {
102
        return 0; // Implementation details
103
    }
104
    
105
    /**
106
     * Concatenate strings
107
     * @param other String to concatenate
108
     * @param encoding Result encoding
109
     * @param lazy Whether to use lazy concatenation
110
     * @return Concatenated string
111
     */
112
    public TruffleString concatUncached(TruffleString other, Encoding encoding, boolean lazy) {
113
        return null; // Implementation details
114
    }
115
    
116
    /**
117
     * Create substring
118
     * @param fromIndex Start index (code points)
119
     * @param length Substring length (code points)
120
     * @param encoding String encoding
121
     * @param lazy Whether to use lazy substring
122
     * @return Substring
123
     */
124
    public TruffleString substringUncached(int fromIndex, int length, Encoding encoding, boolean lazy) {
125
        return null; // Implementation details
126
    }
127
    
128
    /**
129
     * Compare strings
130
     * @param other String to compare
131
     * @param encoding Comparison encoding
132
     * @return Comparison result
133
     */
134
    public int compareToUncached(TruffleString other, Encoding encoding) {
135
        return 0; // Implementation details
136
    }
137
    
138
    /**
139
     * Check string equality
140
     * @param other String to compare
141
     * @param encoding Comparison encoding
142
     * @return true if equal
143
     */
144
    public boolean equalsUncached(TruffleString other, Encoding encoding) {
145
        return false; // Implementation details
146
    }
147
    
148
    /**
149
     * Find substring index
150
     * @param substring Substring to find
151
     * @param fromIndex Start search index
152
     * @param encoding Search encoding
153
     * @return Index of substring or -1
154
     */
155
    public int indexOfStringUncached(TruffleString substring, int fromIndex, Encoding encoding) {
156
        return -1; // Implementation details
157
    }
158
    
159
    /**
160
     * Find last substring index
161
     * @param substring Substring to find
162
     * @param fromIndex Start search index (backward)
163
     * @param encoding Search encoding
164
     * @return Last index of substring or -1
165
     */
166
    public int lastIndexOfStringUncached(TruffleString substring, int fromIndex, Encoding encoding) {
167
        return -1; // Implementation details
168
    }
169
    
170
    /**
171
     * Get code point at index
172
     * @param index Code point index
173
     * @param encoding String encoding
174
     * @return Code point value
175
     */
176
    public int codePointAtIndexUncached(int index, Encoding encoding) {
177
        return 0; // Implementation details
178
    }
179
    
180
    /**
181
     * Copy to byte array
182
     * @param srcIndex Source start index (code points)
183
     * @param dst Destination byte array
184
     * @param dstIndex Destination start index
185
     * @param length Copy length (code points)
186
     * @param encoding Source encoding
187
     */
188
    public void copyToByteArrayUncached(int srcIndex, byte[] dst, int dstIndex, int length, Encoding encoding) {
189
        // Implementation details
190
    }
191
}
192

193
/**
194
 * Mutable string implementation for building strings
195
 */
196
public final class MutableTruffleString extends AbstractTruffleString {
197
    
198
    /**
199
     * Create mutable string with capacity
200
     * @param encoding String encoding
201
     * @param capacity Initial capacity
202
     * @return MutableTruffleString instance
203
     */
204
    public static MutableTruffleString create(Encoding encoding, int capacity) {
205
        return null; // Implementation details
206
    }
207
    
208
    /**
209
     * Write code point at index
210
     * @param index Write index
211
     * @param codePoint Code point to write
212
     * @param encoding String encoding
213
     */
214
    public void writeCodePointUncached(int index, int codePoint, Encoding encoding) {
215
        // Implementation details
216
    }
217
    
218
    /**
219
     * Convert to immutable string
220
     * @param encoding String encoding
221
     * @return Immutable TruffleString
222
     */
223
    public TruffleString toImmutableUncached(Encoding encoding) {
224
        return null; // Implementation details
225
    }
226
}
227

228
/**
229
 * Builder for constructing strings efficiently
230
 */
231
public final class TruffleStringBuilder {
232
    
233
    /**
234
     * Create string builder
235
     * @param encoding Target encoding
236
     * @return Builder instance
237
     */
238
    public static TruffleStringBuilder create(Encoding encoding) {
239
        return null; // Implementation details
240
    }
241
    
242
    /**
243
     * Create string builder with capacity
244
     * @param encoding Target encoding
245
     * @param capacity Initial capacity
246
     * @return Builder instance
247
     */
248
    public static TruffleStringBuilder create(Encoding encoding, int capacity) {
249
        return null; // Implementation details
250
    }
251
    
252
    /**
253
     * Append string
254
     * @param string String to append
255
     * @return This builder
256
     */
257
    public TruffleStringBuilder appendStringUncached(TruffleString string) {
258
        return this; // Implementation details
259
    }
260
    
261
    /**
262
     * Append Java string
263
     * @param javaString Java string to append
264
     * @return This builder
265
     */
266
    public TruffleStringBuilder appendJavaStringUTF16Uncached(String javaString) {
267
        return this; // Implementation details
268
    }
269
    
270
    /**
271
     * Append code point
272
     * @param codePoint Code point to append
273
     * @return This builder
274
     */
275
    public TruffleStringBuilder appendCodePointUncached(int codePoint) {
276
        return this; // Implementation details
277
    }
278
    
279
    /**
280
     * Build final string
281
     * @return TruffleString instance
282
     */
283
    public TruffleString toStringUncached() {
284
        return null; // Implementation details
285
    }
286
    
287
    /**
288
     * Get current length
289
     * @return Length in code points
290
     */
291
    public int lengthUncached() {
292
        return 0; // Implementation details
293
    }
294
}
295

296
/**
297
 * Iterator for traversing strings
298
 */
299
public final class TruffleStringIterator {
300
    
301
    /**
302
     * Create iterator for string
303
     * @param string String to iterate
304
     * @param encoding String encoding
305
     * @return Iterator instance
306
     */
307
    public static TruffleStringIterator create(TruffleString string, Encoding encoding) {
308
        return null; // Implementation details
309
    }
310
    
311
    /**
312
     * Check if more code points available
313
     * @return true if has next
314
     */
315
    public boolean hasNext() {
316
        return false; // Implementation details
317
    }
318
    
319
    /**
320
     * Get next code point
321
     * @return Next code point
322
     */
323
    public int nextUncached() {
324
        return 0; // Implementation details
325
    }
326
    
327
    /**
328
     * Check if more code points available (backward)
329
     * @return true if has previous
330
     */
331
    public boolean hasPrevious() {
332
        return false; // Implementation details
333
    }
334
    
335
    /**
336
     * Get previous code point
337
     * @return Previous code point
338
     */
339
    public int previousUncached() {
340
        return 0; // Implementation details
341
    }
342
}
343

344
/**
345
 * Encoding definitions and utilities
346
 */
347
public final class Encodings {
348
    
349
    /**
350
     * UTF-8 encoding
351
     */
352
    public static final Encoding UTF_8 = null;
353
    
354
    /**
355
     * UTF-16 encoding
356
     */
357
    public static final Encoding UTF_16 = null;
358
    
359
    /**
360
     * UTF-32 encoding
361
     */
362
    public static final Encoding UTF_32 = null;
363
    
364
    /**
365
     * ISO-8859-1 (Latin-1) encoding
366
     */
367
    public static final Encoding ISO_8859_1 = null;
368
    
369
    /**
370
     * US-ASCII encoding
371
     */
372
    public static final Encoding US_ASCII = null;
373
    
374
    /**
375
     * Get encoding by name
376
     * @param name Encoding name
377
     * @return Encoding instance or null
378
     */
379
    public static Encoding getEncoding(String name) {
380
        return null; // Implementation details
381
    }
382
}
383

384
/**
385
 * String encoding descriptor
386
 */
387
public abstract class Encoding {
388
    
389
    /**
390
     * Get encoding name
391
     * @return Encoding name
392
     */
393
    public abstract String getName();
394
    
395
    /**
396
     * Get maximum bytes per code point
397
     * @return Maximum bytes per code point
398
     */
399
    public abstract int getMaxBytesPerCodePoint();
400
    
401
    /**
402
     * Check if encoding is fixed width
403
     * @return true if fixed width
404
     */
405
    public abstract boolean isFixedWidth();
406
}
407
```
408

409
### Performance Profiling
410

411
Profiling utilities for optimizing node execution through speculation and type feedback.
412

413
```java { .api }
414
/**
415
 * Base class for all performance profiles
416
 */
417
public abstract class Profile {
418
    
419
    /**
420
     * Disable profiling for this profile
421
     * @return Disabled profile instance
422
     */
423
    public abstract Profile disable();
424
    
425
    /**
426
     * Reset profile statistics
427
     */
428
    public abstract void reset();
429
    
430
    /**
431
     * Check if profile is generic (no optimization)
432
     * @return true if generic
433
     */
434
    public abstract boolean isGeneric();
435
    
436
    /**
437
     * Check if profile is uninitialized
438
     * @return true if uninitialized
439
     */
440
    public abstract boolean isUninitialized();
441
}
442

443
/**
444
 * Profile for value-based optimizations
445
 */
446
public abstract class ValueProfile extends Profile {
447
    
448
    /**
449
     * Profile value and return cached or new value
450
     * @param value Value to profile
451
     * @return Profiled value
452
     */
453
    public abstract <T> T profile(T value);
454
    
455
    /**
456
     * Create identity-based value profile
457
     * @return ValueProfile instance
458
     */
459
    public static ValueProfile createIdentityProfile() {
460
        return null; // Implementation details
461
    }
462
    
463
    /**
464
     * Create class-based value profile
465
     * @return ValueProfile instance
466
     */
467
    public static ValueProfile createClassProfile() {
468
        return null; // Implementation details
469
    }
470
    
471
    /**
472
     * Create equality-based value profile
473
     * @return ValueProfile instance
474
     */
475
    public static ValueProfile createEqualityProfile() {
476
        return null; // Implementation details
477
    }
478
    
479
    /**
480
     * Get cached value if available
481
     * @return Cached value or null
482
     */
483
    public abstract Object getCachedValue();
484
}
485

486
/**
487
 * Specialized value profile for primitive int values
488
 */
489
public abstract class IntValueProfile extends Profile {
490
    
491
    /**
492
     * Profile int value
493
     * @param value Value to profile
494
     * @return Profiled value
495
     */
496
    public abstract int profile(int value);
497
    
498
    /**
499
     * Create int value profile
500
     * @return IntValueProfile instance
501
     */
502
    public static IntValueProfile create() {
503
        return null; // Implementation details
504
    }
505
}
506

507
/**
508
 * Specialized value profile for primitive long values
509
 */
510
public abstract class LongValueProfile extends Profile {
511
    
512
    /**
513
     * Profile long value
514
     * @param value Value to profile
515
     * @return Profiled value
516
     */
517
    public abstract long profile(long value);
518
    
519
    /**
520
     * Create long value profile
521
     * @return LongValueProfile instance
522
     */
523
    public static LongValueProfile create() {
524
        return null; // Implementation details
525
    }
526
}
527

528
/**
529
 * Specialized value profile for primitive double values
530
 */
531
public abstract class DoubleValueProfile extends Profile {
532
    
533
    /**
534
     * Profile double value
535
     * @param value Value to profile
536
     * @return Profiled value
537
     */
538
    public abstract double profile(double value);
539
    
540
    /**
541
     * Create double value profile
542
     * @return DoubleValueProfile instance
543
     */
544
    public static DoubleValueProfile create() {
545
        return null; // Implementation details
546
    }
547
}
548

549
/**
550
 * Specialized value profile for primitive float values
551
 */
552
public abstract class FloatValueProfile extends Profile {
553
    
554
    /**
555
     * Profile float value
556
     * @param value Value to profile
557
     * @return Profiled value
558
     */
559
    public abstract float profile(float value);
560
    
561
    /**
562
     * Create float value profile  
563
     * @return FloatValueProfile instance
564
     */
565
    public static FloatValueProfile create() {
566
        return null; // Implementation details
567
    }
568
}
569

570
/**
571
 * Profile for branch conditions
572
 */
573
public abstract class ConditionProfile extends Profile {
574
    
575
    /**
576
     * Profile boolean condition
577
     * @param condition Condition to profile
578
     * @return Profiled condition
579
     */
580
    public abstract boolean profile(boolean condition);
581
    
582
    /**
583
     * Create binary condition profile (true/false)
584
     * @return ConditionProfile instance
585
     */
586
    public static ConditionProfile createBinaryProfile() {
587
        return null; // Implementation details
588
    }
589
    
590
    /**
591
     * Create counting condition profile
592
     * @return ConditionProfile instance
593
     */
594
    public static ConditionProfile createCountingProfile() {
595
        return null; // Implementation details
596
    }
597
    
598
    /**
599
     * Get true count
600
     * @return Number of true results
601
     */
602
    public abstract long getTrueCount();
603
    
604
    /**
605
     * Get false count
606
     * @return Number of false results
607
     */
608
    public abstract long getFalseCount();
609
}
610

611
/**
612
 * Profile for method execution frequency
613
 */
614
public abstract class BranchProfile extends Profile {
615
    
616
    /**
617
     * Enter this branch
618
     */
619
    public abstract void enter();
620
    
621
    /**
622
     * Check if branch was visited
623
     * @return true if visited
624
     */
625
    public abstract boolean wasVisited();
626
    
627
    /**
628
     * Create branch profile
629
     * @return BranchProfile instance
630
     */
631
    public static BranchProfile create() {
632
        return null; // Implementation details
633
    }
634
}
635

636
/**
637
 * Profile optimized for loop conditions
638
 */
639
public abstract class LoopConditionProfile extends Profile {
640
    
641
    /**
642
     * Profile loop condition
643
     * @param condition Loop condition
644
     * @return Profiled condition
645
     */
646
    public abstract boolean profile(boolean condition);
647
    
648
    /**
649
     * Inject loop condition profiling
650
     * @param condition Loop condition
651
     * @return Profiled condition
652
     */
653
    public abstract boolean inject(boolean condition);
654
    
655
    /**
656
     * Create loop condition profile
657
     * @return LoopConditionProfile instance
658
     */
659
    public static LoopConditionProfile create() {
660
        return null; // Implementation details
661
    }
662
}
663
```
664

665
### Exception Handling
666

667
Optimized exception handling for Truffle languages with stack trace management.
668

669
```java { .api }
670
/**
671
 * Base class for Truffle language exceptions
672
 */
673
public abstract class AbstractTruffleException extends RuntimeException implements TruffleObject {
674
    
675
    /**
676
     * Create exception without message
677
     */
678
    protected AbstractTruffleException() {
679
        super();
680
    }
681
    
682
    /**
683
     * Create exception with message
684
     * @param message Exception message
685
     */
686
    protected AbstractTruffleException(String message) {
687
        super(message);
688
    }
689
    
690
    /**
691
     * Create exception with message and cause
692
     * @param message Exception message
693
     * @param cause Exception cause
694
     */
695
    protected AbstractTruffleException(String message, Throwable cause) {
696
        super(message, cause);
697
    }
698
    
699
    /**
700
     * Create exception with cause
701
     * @param cause Exception cause
702
     */
703
    protected AbstractTruffleException(Throwable cause) {
704
        super(cause);
705
    }
706
    
707
    /**
708
     * Get stack trace element limit
709
     * @return Maximum stack trace elements
710
     */
711
    public final int getStackTraceElementLimit() {
712
        return 0; // Implementation details
713
    }
714
    
715
    /**
716
     * Check if exception is internal
717
     * @return true if internal
718
     */
719
    public boolean isInternalError() {
720
        return false;
721
    }
722
    
723
    /**
724
     * Get exception location
725
     * @return Node where exception occurred
726
     */
727
    public Node getLocation() {
728
        return null; // Implementation details
729
    }
730
    
731
    /**
732
     * Get exception type for interop
733
     * @return ExceptionType enum value
734
     */
735
    public ExceptionType getExceptionType() {
736
        return ExceptionType.RUNTIME_ERROR;
737
    }
738
    
739
    /**
740
     * Check if exception has source location
741
     * @return true if has location
742
     */
743
    public boolean hasSourceLocation() {
744
        return getLocation() != null;
745
    }
746
    
747
    /**
748
     * Get source location
749
     * @return SourceSection or null
750
     */
751
    public SourceSection getSourceLocation() {
752
        Node location = getLocation();
753
        return location != null ? location.getSourceSection() : null;
754
    }
755
}
756

757
/**
758
 * Default stack trace element implementation
759
 */
760
public final class DefaultStackTraceElementObject implements TruffleObject {
761
    
762
    /**
763
     * Create stack trace element
764
     * @param rootNode Root node for frame
765
     * @param sourceSection Source section
766
     * @return Stack trace element
767
     */
768
    public static DefaultStackTraceElementObject create(RootNode rootNode, SourceSection sourceSection) {
769
        return new DefaultStackTraceElementObject(rootNode, sourceSection);
770
    }
771
    
772
    private DefaultStackTraceElementObject(RootNode rootNode, SourceSection sourceSection) {
773
        // Implementation details
774
    }
775
    
776
    /**
777
     * Get root node
778
     * @return RootNode instance
779
     */
780
    public RootNode getRootNode() {
781
        return null; // Implementation details
782
    }
783
    
784
    /**
785
     * Get source section
786
     * @return SourceSection instance
787
     */
788
    public SourceSection getSourceSection() {
789
        return null; // Implementation details
790
    }
791
}
792

793
/**
794
 * Host stack trace element for host interop
795
 */
796
public final class HostStackTraceElementObject implements TruffleObject {
797
    
798
    /**
799
     * Create host stack trace element
800
     * @param element Java StackTraceElement
801
     * @return Host stack trace element
802
     */
803
    public static HostStackTraceElementObject create(StackTraceElement element) {
804
        return new HostStackTraceElementObject(element);
805
    }
806
    
807
    private HostStackTraceElementObject(StackTraceElement element) {
808
        // Implementation details
809
    }
810
    
811
    /**
812
     * Get Java stack trace element
813
     * @return StackTraceElement instance
814
     */
815
    public StackTraceElement getStackTraceElement() {
816
        return null; // Implementation details
817
    }
818
}
819
```
820

821
### Dynamic Object System
822

823
High-performance object implementation with shape-based optimization.
824

825
```java { .api }
826
/**
827
 * Base class for dynamic objects in Truffle
828
 */
829
public abstract class DynamicObject implements TruffleObject {
830
    
831
    /**
832
     * Get object shape
833
     * @return Shape instance
834
     */
835
    public abstract Shape getShape();
836
    
837
    /**
838
     * Get property value
839
     * @param key Property key
840
     * @return Property value
841
     */
842
    public abstract Object get(Object key);
843
    
844
    /**
845
     * Get property value with default
846
     * @param key Property key
847
     * @param defaultValue Default value if not found
848
     * @return Property value or default
849
     */
850
    public abstract Object getOrDefault(Object key, Object defaultValue);
851
    
852
    /**
853
     * Set property value
854
     * @param key Property key
855
     * @param value Property value
856
     * @return true if successful
857
     */
858
    public abstract boolean set(Object key, Object value);
859
    
860
    /**
861
     * Check if property exists
862
     * @param key Property key
863
     * @return true if property exists
864
     */
865
    public abstract boolean containsKey(Object key);
866
    
867
    /**
868
     * Define property with attributes
869
     * @param key Property key
870
     * @param value Property value
871
     * @param flags Property flags
872
     * @return true if successful
873
     */
874
    public abstract boolean define(Object key, Object value, int flags);
875
    
876
    /**
877
     * Delete property
878
     * @param key Property key
879
     * @return true if successful
880
     */
881
    public abstract boolean delete(Object key);
882
    
883
    /**
884
     * Get property count
885
     * @return Number of properties
886
     */
887
    public abstract int size();
888
    
889
    /**
890
     * Check if object is empty
891
     * @return true if no properties
892
     */
893
    public abstract boolean isEmpty();
894
    
895
    /**
896
     * Copy object
897
     * @param newShape Target shape
898
     * @return Copied object
899
     */
900
    public abstract DynamicObject copy(Shape newShape);
901
}
902

903
/**
904
 * Library for operations on dynamic objects
905
 */
906
public abstract class DynamicObjectLibrary extends Library {
907
    
908
    /**
909
     * Get uncached library instance
910
     * @return Uncached library
911
     */
912
    public static DynamicObjectLibrary getUncached() {
913
        return null; // Implementation details
914
    }
915
    
916
    /**
917
     * Get property value
918
     * @param receiver Dynamic object
919
     * @param key Property key
920
     * @return Property value
921
     * @throws FinalLocationException if location is final
922
     */
923
    public abstract Object getOrDefault(DynamicObject receiver, Object key, Object defaultValue);
924
    
925
    /**
926
     * Set property value
927
     * @param receiver Dynamic object
928
     * @param key Property key
929
     * @param value Property value
930
     * @throws IncompatibleLocationException if incompatible
931
     * @throws FinalLocationException if location is final
932
     */
933
    public abstract void put(DynamicObject receiver, Object key, Object value);
934
    
935
    /**
936
     * Set property value with flags
937
     * @param receiver Dynamic object
938
     * @param key Property key
939
     * @param value Property value
940
     * @param flags Property flags
941
     * @throws IncompatibleLocationException if incompatible
942
     * @throws FinalLocationException if location is final
943
     */
944
    public abstract void putWithFlags(DynamicObject receiver, Object key, Object value, int flags);
945
    
946
    /**
947
     * Check if property exists
948
     * @param receiver Dynamic object
949
     * @param key Property key
950
     * @return true if property exists
951
     */
952
    public abstract boolean containsKey(DynamicObject receiver, Object key);
953
    
954
    /**
955
     * Get property or null
956
     * @param receiver Dynamic object
957
     * @param key Property key
958
     * @return Property value or null
959
     */
960
    public abstract Object getOrDefault(DynamicObject receiver, Object key, Object defaultValue);
961
    
962
    /**
963
     * Remove property
964
     * @param receiver Dynamic object
965
     * @param key Property key
966
     * @return true if removed
967
     */
968
    public abstract boolean removeKey(DynamicObject receiver, Object key);
969
    
970
    /**
971
     * Get property keys
972
     * @param receiver Dynamic object
973
     * @return Array of property keys
974
     */
975
    public abstract Object[] getKeyArray(DynamicObject receiver);
976
    
977
    /**
978
     * Get property count
979
     * @param receiver Dynamic object
980
     * @return Number of properties
981
     */
982
    public abstract int getShapeFlags(DynamicObject receiver);
983
    
984
    /**
985
     * Mark object as shared
986
     * @param receiver Dynamic object
987
     * @return Shared object
988
     */
989
    public abstract DynamicObject markShared(DynamicObject receiver);
990
    
991
    /**
992
     * Check if object is shared
993
     * @param receiver Dynamic object
994
     * @return true if shared
995
     */
996
    public abstract boolean isShared(DynamicObject receiver);
997
    
998
    /**
999
     * Reset shape
1000
     * @param receiver Dynamic object
1001
     * @param otherShape New shape
1002
     * @return Object with new shape
1003
     */
1004
    public abstract DynamicObject resetShape(DynamicObject receiver, Shape otherShape);
1005
}
1006

1007
/**
1008
 * Object layout descriptor
1009
 */
1010
public abstract class Shape {
1011
    
1012
    /**
1013
     * Get property by key
1014
     * @param key Property key
1015
     * @return Property instance or null
1016
     */
1017
    public abstract Property getProperty(Object key);
1018
    
1019
    /**
1020
     * Get last property in chain
1021
     * @return Property instance
1022
     */
1023
    public abstract Property getLastProperty();
1024
    
1025
    /**
1026
     * Get property list
1027
     * @return List of properties
1028
     */
1029
    public abstract List<Property> getPropertyList();
1030
    
1031
    /**
1032
     * Get property list filtered by predicate
1033
     * @param filter Property filter
1034
     * @return Filtered property list
1035
     */
1036
    public abstract List<Property> getPropertyList(Predicate<Property> filter);
1037
    
1038
    /**
1039
     * Get all property keys
1040
     * @return List of property keys
1041
     */
1042
    public abstract List<Object> getKeys();
1043
    
1044
    /**
1045
     * Get property keys filtered by predicate
1046
     * @param filter Property filter
1047
     * @return Filtered property keys
1048
     */
1049
    public abstract List<Object> getKeys(Predicate<Property> filter);
1050
    
1051
    /**
1052
     * Get property count
1053
     * @return Number of properties
1054
     */
1055
    public abstract int getPropertyCount();
1056
    
1057
    /**
1058
     * Check if shape has property
1059
     * @param key Property key
1060
     * @return true if has property
1061
     */
1062
    public abstract boolean hasProperty(Object key);
1063
    
1064
    /**
1065
     * Create new instance with this shape
1066
     * @return New DynamicObject
1067
     */
1068
    public abstract DynamicObject newInstance();
1069
    
1070
    /**
1071
     * Create child shape with additional property
1072
     * @param key Property key
1073
     * @param location Property location
1074
     * @param flags Property flags
1075
     * @return Child shape
1076
     */
1077
    public abstract Shape defineProperty(Object key, Object value, int flags);
1078
    
1079
    /**
1080
     * Get shared version of shape
1081
     * @return Shared shape
1082
     */
1083
    public abstract Shape makeSharedShape();
1084
    
1085
    /**
1086
     * Check if shape is shared
1087
     * @return true if shared
1088
     */
1089
    public abstract boolean isShared();
1090
    
1091
    /**
1092
     * Check if shape is valid
1093
     * @return true if valid
1094
     */
1095
    public abstract boolean isValid();
1096
}
1097
```
1098

1099
## Types
1100

1101
### Utility Data Structures
1102

1103
```java { .api }
1104
/**
1105
 * Three-valued logic enumeration
1106
 */
1107
public enum TriState {
1108
    TRUE, FALSE, UNDEFINED;
1109
    
1110
    /**
1111
     * Convert to boolean with default
1112
     * @param defaultValue Default value for UNDEFINED
1113
     * @return boolean value
1114
     */
1115
    public boolean toBoolean(boolean defaultValue) {
1116
        switch (this) {
1117
            case TRUE: return true;
1118
            case FALSE: return false;
1119
            default: return defaultValue;
1120
        }
1121
    }
1122
    
1123
    /**
1124
     * Create from boolean
1125
     * @param value boolean value
1126
     * @return TriState value
1127
     */
1128
    public static TriState valueOf(boolean value) {
1129
        return value ? TRUE : FALSE;
1130
    }
1131
}
1132

1133
/**
1134
 * Immutable bit set implementation
1135
 */
1136
public final class FinalBitSet implements Cloneable {
1137
    
1138
    /**
1139
     * Create empty bit set
1140
     * @return Empty FinalBitSet
1141
     */
1142
    public static FinalBitSet create() {
1143
        return new FinalBitSet();
1144
    }
1145
    
1146
    /**
1147
     * Create bit set from long
1148
     * @param value Long value
1149
     * @return FinalBitSet instance
1150
     */
1151
    public static FinalBitSet create(long value) {
1152
        return new FinalBitSet(value);
1153
    }
1154
    
1155
    /**
1156
     * Check if bit is set
1157
     * @param bitIndex Bit index
1158
     * @return true if set
1159
     */
1160
    public boolean get(int bitIndex) {
1161
        return false; // Implementation details
1162
    }
1163
    
1164
    /**
1165
     * Set bit and return new bit set
1166
     * @param bitIndex Bit index
1167
     * @return New FinalBitSet with bit set
1168
     */
1169
    public FinalBitSet set(int bitIndex) {
1170
        return this; // Implementation details
1171
    }
1172
    
1173
    /**
1174
     * Clear bit and return new bit set
1175
     * @param bitIndex Bit index
1176
     * @return New FinalBitSet with bit cleared
1177
     */
1178
    public FinalBitSet clear(int bitIndex) {
1179
        return this; // Implementation details
1180
    }
1181
    
1182
    /**
1183
     * Get bit count
1184
     * @return Number of set bits
1185
     */
1186
    public int cardinality() {
1187
        return 0; // Implementation details
1188
    }
1189
    
1190
    /**
1191
     * Check if empty
1192
     * @return true if no bits set
1193
     */
1194
    public boolean isEmpty() {
1195
        return false; // Implementation details
1196
    }
1197
}
1198

1199
/**
1200
 * Weak reference implementation for Truffle
1201
 */
1202
public final class TruffleWeakReference<T> {
1203
    
1204
    /**
1205
     * Create weak reference
1206
     * @param referent Target object
1207
     * @return Weak reference
1208
     */
1209
    public static <T> TruffleWeakReference<T> create(T referent) {
1210
        return new TruffleWeakReference<>(referent);
1211
    }
1212
    
1213
    private TruffleWeakReference(T referent) {
1214
        // Implementation details
1215
    }
1216
    
1217
    /**
1218
     * Get referenced object
1219
     * @return Referenced object or null
1220
     */
1221
    public T get() {
1222
        return null; // Implementation details
1223
    }
1224
    
1225
    /**
1226
     * Clear reference
1227
     */
1228
    public void clear() {
1229
        // Implementation details
1230
    }
1231
}
1232

1233
/**
1234
 * JSON helper utilities
1235
 */
1236
public final class JSONHelper {
1237
    
1238
    /**
1239
     * Parse JSON string
1240
     * @param jsonString JSON string
1241
     * @return Parsed object
1242
     */
1243
    public static Object parseJSON(String jsonString) {
1244
        return null; // Implementation details
1245
    }
1246
    
1247
    /**
1248
     * Convert object to JSON string
1249
     * @param object Object to convert
1250
     * @return JSON string
1251
     */
1252
    public static String toJSONString(Object object) {
1253
        return null; // Implementation details
1254
    }
1255
}
1256
```