Add String#byte_index(Char)

spec/std/string_spec.cr

@@ -1277,6 +1277,19 @@ describe "String" do
       "Dizzy Miss Lizzy".byte_index('z'.ord, -17).should be_nil
     }
 
+    it { "foo".byte_index('o').should eq(1) }
+    it { "foo bar booz".byte_index('o', 3).should eq(9) }
+    it { "foo".byte_index('a').should be_nil }
+    it { "foo".byte_index('a').should be_nil }
+    it { "foo".byte_index('o', 3).should be_nil }
+    it { "Hi, 💣".byte_index('💣').should eq(4) }
+    it {
+      "Dizzy Miss Lizzy".byte_index('z').should eq(2)
+      "Dizzy Miss Lizzy".byte_index('z', 3).should eq(3)
+      "Dizzy Miss Lizzy".byte_index('z', -4).should eq(13)
+      "Dizzy Miss Lizzy".byte_index('z', -17).should be_nil
+    }
+
     it "gets byte index of string" do
       "hello world".byte_index("he").should eq(0)
       "hello world".byte_index("lo").should eq(3)

src/string.cr

@@ -3670,6 +3670,49 @@ class String
     nil
   end
 
+  # Returns the index of the _first_ occurrence of *char* in the string, or `nil` if not present.
+  # If *offset* is present, it defines the position to start the search.
+  #
+  # Negative *offset* can be used to start the search from the end of the string.
+  #
+  # ```
+  # "Hello, World".byte_index('o')          # => 4
+  # "Hello, World".byte_index('Z')          # => nil
+  # "Hello, World".byte_index('o', 5)       # => 8
+  # "Hi, 💣".byte_index('💣')                 # => 4
+  # "Dizzy Miss Lizzy".byte_index('z')      # => 2
+  # "Dizzy Miss Lizzy".byte_index('z', 3)   # => 3
+  # "Dizzy Miss Lizzy".byte_index('z', -4)  # => 13
+  # "Dizzy Miss Lizzy".byte_index('z', -17) # => nil
+  # ```
+  def byte_index(char : Char, offset = 0) : Int32?
+    return byte_index(char.ord, offset) if char.ascii?
+
+    offset += bytesize if offset < 0
+    return if offset < 0
+    return if offset + char.bytesize > bytesize
+
+    # Simplified "Rabin-Karp" algorithm
+    search_hash = 0u32
+    search_mask = 0u32
+    hash = 0u32
+    char.each_byte do |byte|
+      search_hash = (search_hash << 8) | byte
+      search_mask = (search_mask << 8) | 0xff
+      hash = (hash << 8) | to_unsafe[offset]
+      offset += 1
+    end
+
+    offset.upto(bytesize) do |i|
+      if (hash & search_mask) == search_hash
+        return i - char.bytesize
+      end
+      # rely on zero terminating byte
+      hash = (hash << 8) | to_unsafe[i]
+    end
+    nil
+  end
+
   # Returns the byte index of *search* in the string, or `nil` if the string is not present.
   # If *offset* is present, it defines the position to start the search.
   #