API: rename gpiod_chip_find_line()

The name "find_line" is quite ambigous. We should indicate that the purpose of this routine is to map the line name to its HW offset. Kent suggested get_line_get_offset_from_name() which is hard to beat when it comes to being explicit.

Signed-off-by Bartosz Golaszewski <[email protected]>

---
 include/gpiod.h    |  3 ++-
 lib/chip.c         |  3 ++-
 tests/tests-chip.c | 10 +++++++---
 tools/gpiofind.c   |  2 +-
 4 files changed, 12 insertions(+), 6 deletions(-)

include/gpiod.h +2 -1

index c605da8..344a8fc 100644
@@ -158,7 +158,8 @@ struct gpiod_info_event *gpiod_chip_read_info_event(struct gpiod_chip *chip);
  * @note If a line with given name is not exposed by the chip, the function
  *       sets errno to ENOENT.
  */
-int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
+int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
+					 const char *name);
 
 /**
  * @brief Request a set of lines for exclusive usage.

lib/chip.c +2 -1

index edb2dfd..eef3be2 100644
@@ -156,7 +156,8 @@ gpiod_chip_read_info_event(struct gpiod_chip *chip)
 	return gpiod_info_event_read_fd(chip->fd);
 }
 
-GPIOD_API int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name)
+GPIOD_API int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
+						   const char *name)
 {
 	struct gpio_v2_line_info linfo;
 	struct gpiochip_info chinfo;

tests/tests-chip.c +7 -3

index 3fad16d..efb4f74 100644
@@ -88,7 +88,9 @@ GPIOD_TEST_CASE(find_line_bad)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "nonexistent"), ==, -1);
+	g_assert_cmpint(
+		gpiod_chip_get_line_offset_from_name(chip,
+						     "nonexistent"), ==, -1);
 	gpiod_test_expect_errno(ENOENT);
 }
 

@@ -112,7 +114,8 @@ GPIOD_TEST_CASE(find_line_good)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 4);
+	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
+			==, 4);
 }
 
 /* Verify that for duplicated line names, the first one is returned. */

@@ -136,5 +139,6 @@ GPIOD_TEST_CASE(find_line_duplicate)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 2);
+	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
+			==, 2);
 }

tools/gpiofind.c +1 -1

index 36eba86..03b15c9 100644
@@ -75,7 +75,7 @@ int main(int argc, char **argv)
 			die_perror("unable to open %s", entries[i]->d_name);
 		}
 
-		offset = gpiod_chip_find_line(chip, argv[0]);
+		offset = gpiod_chip_get_line_offset_from_name(chip, argv[0]);
 		if (offset >= 0) {
 			info = gpiod_chip_get_info(chip);
 			if (!info)

Signature · 1 line

2.32.0

Quoted 5 lines · Bartosz Golaszewski

The name "find_line" is quite ambigous. We should indicate that the purpose of this routine is to map the line name to its HW offset. Kent suggested get_line_get_offset_from_name() which is hard to beat when it comes to being explicit.

My suggestion was actually gpiod_chip_line_offset_from_name(). But gpiod_chip_get_line_offset_from_name() is even more explicit. And both make more sense than your misquote above ;-).

So that works for me - assuming you fix the quote.

The name "find_line" is quite ambigous. We should indicate that the purpose of this routine is to map the line name to its HW offset. Kent suggested get_line_get_offset_from_name() which is hard to beat when it comes to being explicit.

Signed-off-by Bartosz Golaszewski <[email protected]>

---