[Macros] Add versions of the CLAY_ID macros that take Clay_String (#285)

.github/workflows/cmake-multi-platform.yml

@@ -53,7 +53,7 @@ jobs:
         echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT"
 
     - name: Cache
-      uses: actions/cache@v4.0.2
+      uses: actions/cache@v4.2.0
       with:
         # A list of files, directories, and wildcard patterns to cache and restore
         path: "/home/runner/work/clay/clay/build/_deps"

README.md

@@ -897,18 +897,12 @@ Element is subject to [culling](#visibility-culling). Otherwise, multiple `Clay_
 
 ### CLAY_ID
 
-**Usage**
+`Clay_ElementId CLAY_ID(STRING_LITERAL idString)`
-
-`CLAY(CLAY_ID(char* idString)) {}`
-
-**Lifecycle**
-
-`Clay_BeginLayout()` -> `CLAY(` -> `CLAY_ID()` -> `)` -> `Clay_EndLayout()` 
-
-**Notes**
 
 **CLAY_ID()** is used to generate and attach a [Clay_ElementId](#clay_elementid) to a layout element during declaration.
 
+Note this macro only works with String literals and won't compile if used with a `char*` variable. To use a heap allocated `char*` string as an ID, use [CLAY_SID](#clay_sid). 
+
 To regenerate the same ID outside of layout declaration when using utility functions such as [Clay_PointerOver](#clay_pointerover), use the [Clay_GetElementId](#clay_getelementid) function.
 
 **Examples**
@@ -931,11 +925,31 @@ if (buttonIsHovered && leftMouseButtonPressed) {
 
 ---
 
+### CLAY_SID()
+
+`Clay_ElementId CLAY_SID(Clay_String idString)`
+
+A version of [CLAY_ID](#clay_id) that can be used with heap allocated `char *` data. The underlying `char` data will not be copied internally and should live until at least the next frame.
+
+---
+
 ### CLAY_IDI()
 
-`Clay_ElementId CLAY_IDI(char *label, int32_t index)`
+`Clay_ElementId CLAY_IDI(STRING_LITERAL idString, int32_t index)`
 
-An offset version of [CLAY_ID](#clay_id). Generates a [Clay_ElementId](#clay_elementid) string id from the provided `char *label`, combined with the `int index`. Used for generating ids for sequential elements (such as in a `for` loop) without having to construct dynamic strings at runtime.
+An offset version of [CLAY_ID](#clay_id). Generates a [Clay_ElementId](#clay_elementid) string id from the provided `char *label`, combined with the `int index`.
+
+Used for generating ids for sequential elements (such as in a `for` loop) without having to construct dynamic strings at runtime.
+
+Note this macro only works with String literals and won't compile if used with a `char*` variable. To use a heap allocated `char*` string as an ID, use [CLAY_SIDI](#clay_sidi).
+
+---
+
+### CLAY_SIDI()
+
+`Clay_ElementId CLAY_SIDI(Clay_String idString, int32_t index)`
+
+A version of [CLAY_IDI](#clay_idi) that can be used with heap allocated `char *` data. The underlying `char` data will not be copied internally and should live until at least the next frame.
 
 ---
 
@@ -943,7 +957,7 @@ An offset version of [CLAY_ID](#clay_id). Generates a [Clay_ElementId](#clay_ele
 
 **Usage**
 
-`CLAY(CLAY_ID_LOCAL(char* idString)) {}`
+`Clay_ElementId CLAY_ID_LOCAL(STRING_LITERAL idString)`
 
 **Lifecycle**
 
@@ -957,6 +971,8 @@ Unlike [CLAY_ID](#clay_id) which needs to be globally unique, a local ID is base
 
 As a result, local id is suitable for use in reusable components and loops.
 
+Note this macro only works with String literals and won't compile if used with a `char*` variable. To use a heap allocated `char*` string as an ID, use [CLAY_SID_LOCAL](#clay_sid_local).
+
 **Examples**
 
 ```C
@@ -976,11 +992,31 @@ for (int i = 0; i < headerButtons.length; i++) {
 
 ---
 
+### CLAY_SID_LOCAL()
+
+`Clay_ElementId CLAY_SID_LOCAL(Clay_String idString)`
+
+A version of [CLAY_ID_LOCAL](#clay_id_local) that can be used with heap allocated `char *` data. The underlying `char` data will not be copied internally and should live until at least the next frame.
+
+---
+
 ### CLAY_IDI_LOCAL()
 
-`Clay_ElementId CLAY_IDI_LOCAL(char *label, int32_t index)`
+`Clay_ElementId CLAY_IDI_LOCAL(STRING_LITERAL idString, int32_t index)`
 
-An offset version of [CLAY_ID_LOCAL](#clay_local_id). Generates a [Clay_ElementId](#clay_elementid) string id from the provided `char *label`, combined with the `int index`. Used for generating ids for sequential elements (such as in a `for` loop) without having to construct dynamic strings at runtime.
+An offset version of [CLAY_ID_LOCAL](#clay_local_id). Generates a [Clay_ElementId](#clay_elementid) string id from the provided `char *label`, combined with the `int index`.
+
+Used for generating ids for sequential elements (such as in a `for` loop) without having to construct dynamic strings at runtime.
+
+Note this macro only works with String literals and won't compile if used with a `char*` variable. To use a heap allocated `char*` string as an ID, use [CLAY_SIDI_LOCAL](#clay_sidi_local).
+
+---
+
+### CLAY_SIDI_LOCAL()
+
+`Clay_ElementId CLAY_SIDI_LOCAL(Clay_String idString, int32_t index)`
+
+A version of [CLAY_IDI_LOCAL](#clay_idi_local) that can be used with heap allocated `char *` data. The underlying `char` data will not be copied internally and should live until at least the next frame.
 
 ---
 

clay.h

@@ -71,13 +71,25 @@
 
 #define CLAY_SIZING_PERCENT(percentOfParent) (CLAY__INIT(Clay_SizingAxis) { .size = { .percent = (percentOfParent) }, .type = CLAY__SIZING_TYPE_PERCENT })
 
+// Note: If a compile error led you here, you might be trying to use CLAY_ID with something other than a string literal. To construct an ID with a dynamic string, use CLAY_SID instead.
 #define CLAY_ID(label) CLAY_IDI(label, 0)
 
-#define CLAY_IDI(label, index) Clay__HashString(CLAY_STRING(label), index, 0)
+#define CLAY_SID(label) CLAY_SIDI(label, 0)
 
+// Note: If a compile error led you here, you might be trying to use CLAY_IDI with something other than a string literal. To construct an ID with a dynamic string, use CLAY_SIDI instead.
+#define CLAY_IDI(label, index) CLAY_SIDI(CLAY_STRING(label), index)
+
+#define CLAY_SIDI(label, index) Clay__HashString(label, index, 0)
+
+// Note: If a compile error led you here, you might be trying to use CLAY_ID_LOCAL with something other than a string literal. To construct an ID with a dynamic string, use CLAY_SID_LOCAL instead.
 #define CLAY_ID_LOCAL(label) CLAY_IDI_LOCAL(label, 0)
 
-#define CLAY_IDI_LOCAL(label, index) Clay__HashString(CLAY_STRING(label), index, Clay__GetParentElementId())
+#define CLAY_SID_LOCAL(label) CLAY_SIDI_LOCAL(label, 0)
+
+// Note: If a compile error led you here, you might be trying to use CLAY_IDI_LOCAL with something other than a string literal. To construct an ID with a dynamic string, use CLAY_SIDI_LOCAL instead.
+#define CLAY_IDI_LOCAL(label, index) CLAY_SIDI_LOCAL(CLAY_STRING(label), index)
+
+#define CLAY_SIDI_LOCAL(label, index) Clay__HashString(label, index, Clay__GetParentElementId())
 
 #define CLAY__STRING_LENGTH(s) ((sizeof(s) / sizeof((s)[0])) - sizeof((s)[0]))