upb/message/array.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2023 Google LLC.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 #ifndef UPB_MESSAGE_ARRAY_H_
0009 #define UPB_MESSAGE_ARRAY_H_
0010
0011 #include <stddef.h>
0012
0013 #include "upb/base/descriptor_constants.h"
0014 #include "upb/mem/arena.h"
0015 #include "upb/message/internal/array.h"
0016 #include "upb/message/value.h"
0017 #include "upb/mini_table/field.h"
0018 #include "upb/mini_table/message.h"
0019
0020 // Must be last.
0021 #include "upb/port/def.inc"
0022
0023 typedef struct upb_Array upb_Array;
0024
0025 #ifdef __cplusplus
0026 extern "C" {
0027 #endif
0028
0029 // Creates a new array on the given arena that holds elements of this type.
0030 UPB_API upb_Array* upb_Array_New(upb_Arena* a, upb_CType type);
0031
0032 // Returns the number of elements in the array.
0033 UPB_API_INLINE size_t upb_Array_Size(const upb_Array* arr);
0034
0035 // Returns the given element, which must be within the array's current size.
0036 UPB_API upb_MessageValue upb_Array_Get(const upb_Array* arr, size_t i);
0037
0038 // Returns a mutating pointer to the given element, which must be within the
0039 // array's current size.
0040 UPB_API upb_MutableMessageValue upb_Array_GetMutable(upb_Array* arr, size_t i);
0041
0042 // Sets the given element, which must be within the array's current size.
0043 UPB_API void upb_Array_Set(upb_Array* arr, size_t i, upb_MessageValue val);
0044
0045 // Appends an element to the array. Returns false on allocation failure.
0046 UPB_API bool upb_Array_Append(upb_Array* array, upb_MessageValue val,
0047                               upb_Arena* arena);
0048
0049 // Moves elements within the array using memmove().
0050 // Like memmove(), the source and destination elements may be overlapping.
0051 UPB_API void upb_Array_Move(upb_Array* array, size_t dst_idx, size_t src_idx,
0052                             size_t count);
0053
0054 // Inserts one or more empty elements into the array.
0055 // Existing elements are shifted right.
0056 // The new elements have undefined state and must be set with `upb_Array_Set()`.
0057 // REQUIRES: `i <= upb_Array_Size(arr)`
0058 UPB_API bool upb_Array_Insert(upb_Array* array, size_t i, size_t count,
0059                               upb_Arena* arena);
0060
0061 // Deletes one or more elements from the array.
0062 // Existing elements are shifted left.
0063 // REQUIRES: `i + count <= upb_Array_Size(arr)`
0064 UPB_API void upb_Array_Delete(upb_Array* array, size_t i, size_t count);
0065
0066 // Reserves |size| elements of storage for the array.
0067 UPB_API_INLINE bool upb_Array_Reserve(struct upb_Array* array, size_t size,
0068                                       upb_Arena* arena);
0069
0070 // Changes the size of a vector. New elements are initialized to NULL/0.
0071 // Returns false on allocation failure.
0072 UPB_API bool upb_Array_Resize(upb_Array* array, size_t size, upb_Arena* arena);
0073
0074 // Returns pointer to array data.
0075 UPB_API_INLINE const void* upb_Array_DataPtr(const upb_Array* arr);
0076
0077 // Returns mutable pointer to array data.
0078 UPB_API_INLINE void* upb_Array_MutableDataPtr(upb_Array* arr);
0079
0080 // Mark an array and all of its descendents as frozen/immutable.
0081 // If the array elements are messages then |m| must point to the minitable for
0082 // those messages. Otherwise |m| must be NULL.
0083 UPB_API void upb_Array_Freeze(upb_Array* arr, const upb_MiniTable* m);
0084
0085 // Returns whether an array has been frozen.
0086 UPB_API_INLINE bool upb_Array_IsFrozen(const upb_Array* arr);
0087
0088 #ifdef __cplusplus
0089 } /* extern "C" */
0090 #endif
0091
0092 #include "upb/port/undef.inc"
0093
0094 #endif /* UPB_MESSAGE_ARRAY_H_ */