join: add example

Author: perazz

doc/specs/stdlib_strings.md

@@ -494,13 +494,7 @@ The result is of the same type as the elements of `strings` (`type(string_type)`
 #### Example
 
 ```fortran
-! Example usage:
-program test_join
-    type(string_type) :: result
-    type(string_type), dimension(3) :: words = [string_type('hello'), string_type('world'), string_type('fortran')]
-    result = join_string(words, ', ')  ! Joins with comma and space
-    print *, result  ! Output: "hello, world, fortran"
-end program test_join
+{!example/strings/example_join.f90!}
 ```
 
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
@@ -570,3 +564,9 @@ Pure function.
 #### Result value
 
 The result is a `character(kind=c_char)` array with a dimension of `len(value) + 1` to accommodate the null terminator.
+
+#### Example
+
+```fortran
+{!example/strings/example_to_c_string.f90!}
+```

example/strings/CMakeLists.txt

@@ -2,6 +2,7 @@ ADD_EXAMPLE(chomp)
 ADD_EXAMPLE(count)
 ADD_EXAMPLE(ends_with)
 ADD_EXAMPLE(find)
+ADD_EXAMPLE(join)
 ADD_EXAMPLE(padl)
 ADD_EXAMPLE(padr)
 ADD_EXAMPLE(replace_all)

example/strings/example_join.f90

@@ -0,0 +1,21 @@
+program example_join
+  use stdlib_strings, only: join
+  implicit none
+
+  character(len=:), allocatable :: line
+  character(*), parameter :: words(3) = [character(7) :: "Hello", "World", "Fortran"]
+  
+  ! Default separator (space)
+  line = join(words)
+  print *, "'" // line // "'"   !! 'Hello World Fortran'
+
+  ! Custom separator
+  line = join(words, "_")
+  print *, "'" // line // "'"  !! 'Hello_World_Fortran'
+
+  ! Custom 2-character separator
+  line = join(words, ", ")
+  print *, "'" // line // "'"  !! 'Hello, World, Fortran'
+
+  stop 0
+end program example_join