Functions and Character Single Dimension Array
=================================================

In this section, you are going to learn

.. panels::
	:container: container pb-4
	:column: col-lg-12 p-2
	:card: shadow

        What are the calling conventions of character single dimension array ?

.. panels::
	:container: container pb-4
	:column: col-lg-12 p-2
	:card: shadow

	Call by Value

.. panels::
	:container: container pb-4
	:column: col-lg-12 p-2
	:card: shadow

	Call by Reference

.. panels::
	:container: container pb-4
	:column: col-lg-12 p-2
	:card: shadow

	Revisit Basics : :doc:`../../array_n_ptrs/arrays_n_chars/char_sd_array`

.. panels::
	:container: container pb-4
	:column: col-lg-12 p-2
	:card: shadow

	Topics in this section,

		* :ref:`Character Single Dimension Array : Syntax <funcs_n_ptrs_char_sd_array_ex_0_0>`
		* :ref:`Character Single Dimension Array : FAQs <funcs_n_ptrs_char_sd_array_ex_0_1>`
		* :ref:`Character Single Dimension Array : fun(expression) <funcs_n_ptrs_char_sd_array_ex_6>`

                * :ref:`Rules for Call By Value  <funcs_n_ptrs_char_sd_array_rules_for_call_by_value>`

                * :ref:`Rules for Call By Reference <funcs_n_ptrs_char_sd_array_rules_for_call_by_reference>`

                * :ref:`Examples of Call by Value <funcs_n_ptrs_char_sd_array_examples_call_by_value>`

        		* :ref:`Example 1 : Call by Value with [ ] <funcs_n_ptrs_char_sd_array_ex_7>`
		        * :ref:`Example 2 : Call by Value with * <funcs_n_ptrs_char_sd_array_ex_8>`

                * :ref:`Examples of Call by Reference <funcs_n_ptrs_char_sd_array_examples_call_by_reference>`

	        	* :ref:`Example 3 : Call by Reference WITH &a[ ] <funcs_n_ptrs_char_sd_array_ex_9>`
        		* :ref:`Example 4 : Call by Reference WITH (a + x) <funcs_n_ptrs_char_sd_array_ex_10>`
        		* :ref:`Example 5 : Pass full array to a function <funcs_n_ptrs_char_sd_array_ex_12>`
	        	* :ref:`Example 6 : Pass part of the array by reference <funcs_n_ptrs_char_sd_array_ex_13>`
		        * :ref:`Example 7 : Address of full array and Pointer to an Array <funcs_n_ptrs_char_sd_array_ex_14>`

.. _funcs_n_ptrs_char_sd_array_ex_0_0:

.. tab-set::

        .. tab-item:: Character Single Dimension Array : Syntax

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        char array_name[Column];

.. _funcs_n_ptrs_char_sd_array_ex_0_1:

.. tab-set::

        .. tab-item:: Character Single Dimension Array : FAQs

                Consider a Character Single Dimension Array

                .. code-block:: c

                        char a[10];

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        Let us answer few basic questions in this array


.. _funcs_n_ptrs_char_sd_array_ex_6:

.. tab-set::

        .. tab-item:: Character Single Dimension Array : fun(expression)

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			If ``fun(x)`` is the function call, then ``fun(typeof(x))`` is the prototype / definition

		================== =============================== ==========================================================================
		Function Call      Function Definition             Observations
		================== =============================== ==========================================================================
		fun(a[0])          void fun(char x) { }		   * Call by Value
		fun(a[1])          void fun(char x) { }            * Call by Value
		fun(a[9])          void fun(char x) { }            * Call by Value
		fun(&a[0])         void fun(char \*p) { }          * Call by Reference
		fun(&a[1])         void fun(char \*p) { }          * Call by Reference
		fun(&a[9])         void fun(char \*p) { }          * Call by Reference
		fun(\*a)           void fun(char x) { }            * Call by Value
		fun(\*(a + 1))     void fun(char x) { }            * Call by Value
		fun(\*(a + 9))     void fun(char x) { }            * Call by Value
		fun(a)             void fun(char \*p) { }          * Call by Reference
		fun(a + 1)         void fun(char \*p) { }          * Call by Reference
		fun(a + 9)         void fun(char \*p) { }          * Call by Reference
		fun(&a)            void fun(char (\*p) [10] ) { }  * Call by Reference
		================== =============================== ==========================================================================

.. _funcs_n_ptrs_char_sd_array_rules_for_call_by_value:

.. tab-set::

        .. tab-item:: Rules for Call by Value

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        If Declaration has ONE dereference operator, and
        
                                * Expression has ONE dereference operator [], and
        
                                * Expression does not have ``&``
        
                                * then it is call by value

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        If Declaration has ONE dereference operators, and
        
                                * Expression has ONE dereference operator \*, and
        
                                * Expression does not have ``&``
        
                                * then it is call by value

.. _funcs_n_ptrs_char_sd_array_rules_for_call_by_reference:

.. tab-set::

        .. tab-item:: Rules for Call by Reference

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        If Declaration has ONE dereference operator, and

                                * Expression has ONE dereference operators [] or \*, and

                                * Expression has ONE &

                                * then it is call by reference

                                * Example : &a[0]

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        If Declaration has ONE dereference operator, and

                                * Expression has ZERO dereference operator [ ] or \*, and

                                * Expression has ZERO & operator

                                * then it is call by reference

                                * Example : a + 1, a + 4

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        If Declaration has ONE dereference operator, and

                                * Expression has ZERO dereference operator [ ] or \*, and

                                * Expression has ONE & operator

                                * then it is call by reference

                                * Example : &a

.. _funcs_n_ptrs_char_sd_array_examples_call_by_value:

.. tab-set::

        .. tab-item:: Examples of Call by Value

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        Let us look at examples of Call by Value

.. _funcs_n_ptrs_char_sd_array_ex_7:

.. tab-set::

        .. tab-item:: Example 1 : Call by Value with [ ]

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Example for Call By Value with [ ]

		* Step 1 : Define a character array ``a``

		.. code-block:: c

		        char a[10] = "Laptop";

		* Step 2 : Pass an individual character ``a[2]`` to a function. Call by Value

		.. code-block:: c

		        fun(a[2]);

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Individual array elements can be accessed using [ ]

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			In this case ``a[2]`` is third character in the array

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			``a[2]`` is fully dereferenced and there is no ``&`` symbol in ``fun(a[2])``. Hence this is Call By Value

		* Step 3 : Define function ``fun``

		.. code-block:: c

			void fun(char x)
			{

			}

		* Step 4 : Change value of ``x`` inside function ``fun``

		.. code-block:: c

			void fun(char x)
			{
			        printf("x = %c\n", x);
			        x = 'b';
			}

		* See the full program below

		.. code-block:: c

			#include <stdio.h>

			void fun(char x)
			{
			        printf("x = %c\n", x);
			        x = 'b';
			}

			int main(void)
			{
			        char a[10] = "Laptop";

			        fun(a[2]);

			        printf("a = %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			x = p
			a = Laptop

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Changing value of ``x`` inside function ``fun`` DOES NOT change ``a[2]`` in array ``a``

.. _funcs_n_ptrs_char_sd_array_ex_8:

.. tab-set::

        .. tab-item:: Example 2 : Call by Value with ``*``

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Example for Call By Value with ``*``

		* Step 1 : Define a character array ``a``

		.. code-block:: c

		        char a[10] = "Laptop";

		* Step 2 : Pass an individual character ``*(a + 2)`` to a function. Call by Value

		.. code-block:: c

		        fun( *(a + 2) );

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Individual array elements can be accessed using ``*``

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			In this case ``*(a + 2)`` is third character in the array

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			``*(a + 2)`` is fully dereferenced and there is no ``&`` symbol in ``fun( *(a + 2) )``. Hence this is Call By Value

		* Step 3 : Define function ``fun``

		.. code-block:: c

			void fun(char x)
			{

			}

		* Step 4 : Change value of ``x`` inside function ``fun``

		.. code-block:: c

			void fun(char x)
			{
			        printf("x = %c\n", x);
			        x = 'b';
			}

		* See the full program below

		.. code-block:: c

			#include <stdio.h>

			void fun(char x)
			{
			        printf("x = %c\n", x);
			        x = 'b';
			}

			int main(void)
			{
			        char a[10] = "Laptop";

			        fun( *(a + 2) );

			        printf("a = %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			x = p
			a = Laptop

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Changing value of ``x`` inside function ``fun`` DOES NOT change ``*(a + 2)`` in array ``a``

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Remember ``a[2]`` and ``*(a + 2)`` are one and the same

.. _funcs_n_ptrs_char_sd_array_examples_call_by_reference:

.. tab-set::

        .. tab-item:: Examples of Call by Reference

                .. panels::
                        :container: container pb-4
                        :column: col-lg-12 p-2
                        :card: shadow

                        Let us look at examples of Call by Reference

.. _funcs_n_ptrs_char_sd_array_ex_9:

.. tab-set::

        .. tab-item:: Example 3 : Call by Reference WITH &a[ ]

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Example for Call By Reference with ``&a[ ]``

		* Step 1 : Define a character array ``a``

		.. code-block:: c

		        char a[10] = "Laptop";

		* Step 2 : Pass address of an individual character ``&a[2]`` to a function. Call by Reference

		.. code-block:: c

		        fun( &a[2] );

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Address of individual array elements can be accessed using ``&``

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			In this case ``&a[2]`` is the address of third character in the array

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Since we are passing address of third character to function ``fun``, it is called call by reference with respect to third character


		* Step 3 : Define function ``fun``

		.. code-block:: c

			void fun(char *x)
			{

			}

		* Step 4 : Change value of ``*x`` inside function ``fun``

		.. code-block:: c

			void fun(char *x)
			{
			        printf("*x = %c\n", *x);
			        *x = 'b';
			}

		* See the full program below

		.. code-block:: c

			#include <stdio.h>

			void fun(char *x)
			{
			        printf("*x = %c\n", *x);
			        *x = 'b';
			}

			int main(void)
			{
			        char a[10] = "Laptop";

			        fun( &a[2] );

			        printf("a = %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			*x = p
			a = Labtop

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Changing value of ``*x`` inside function ``fun`` CHANGES ``a[2]`` in array ``a``

.. _funcs_n_ptrs_char_sd_array_ex_10:

.. tab-set::

        .. tab-item:: Example 4 : Call by Reference WITH ``(a + x)``

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Example for Call By Reference with ``(a + x)``

		* Step 1 : Define a character array ``a``

		.. code-block:: c

		        char a[10] = "Laptop";

		* Step 2 : Pass address of individual character ``a + 2`` to a function. Call by Reference

		.. code-block:: c

		        fun( a + 2 );

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			In this case ``a + 2`` is the address of third character in the array

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Since we are passing address of third character to function ``fun``, it is called call by reference with respect to third character


		* Step 3 : Define function ``fun``

		.. code-block:: c

			void fun(char *x)
			{

			}

		* Step 4 : Change value of ``*x`` inside function ``fun``

		.. code-block:: c

			void fun(char *x)
			{
			        printf("*x = %c\n", *x);
			        *x = 'b';
			}

		* See the full program below

		.. code-block:: c

			#include <stdio.h>

			void fun(char *x)
			{
			        printf("*x = %c\n", *x);
			        *x = 'b';
			}

			int main(void)
			{
			        char a[10] = "Laptop";

			        fun( a + 2 );

			        printf("a = %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			*x = p
			a = Labtop

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Changing value of ``*x`` inside function ``fun`` CHANGES ``a[2]`` in array ``a``

.. _funcs_n_ptrs_char_sd_array_ex_12:

.. tab-set::

        .. tab-item:: Example 5 : Pass full array array to a function

		* Step 1 : Consider a character array

		.. code-block:: c

			char a[10] = "Laptop123";

		* Step 2 : Pass full array array to a function

		.. code-block:: c

			fun( a );

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Note that we are passing starting address of array

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Hence function ``fun`` has read and write access to all Bytes of array

		* Step 3 : Define a function

		.. code-block:: c

			void fun(char *x)
			{
			        printf("x = %s\n", x);

			        strcpy(x, "Laptop456");
			}

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			function ``fun`` has access to all characters

		* See full program below

		.. code-block:: c

			#include <stdio.h>
			#include <string.h>

			void fun(char *x)
			{
			        printf("x = %s\n", x);

			        strcpy(x, "Laptop456");
			}

			int main(void)
			{
			        char a[10] = "Laptop123";

			        fun(a);

			        printf("a = %s\n", a);

			        return 0;
			}

.. _funcs_n_ptrs_char_sd_array_ex_13:

.. tab-set::

        .. tab-item:: Example 6 : Pass part of the array by reference

		* Step 1 : Consider a character array

		.. code-block:: c

			char a[10] = "Laptop123";

		* Step 2 : Pass full array by reference

		.. code-block:: c

			fun( a + 5 );

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Note that we are passing part of the array by reference

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			In this case, we are passing address of 6th character

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Hence function ``fun`` has read and write access to Bytes 5, 6, 7, 8, 9 in forward direction

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Hence function ``fun`` has read and write access to Bytes 0, 1, 2, 3, 4 in backward direction

		* Step 3 : Define a function

		.. code-block:: c

			void fun(char *x)
			{
			        printf("x = %s\n", x);

			        x[-5] = 'b'; // Same as a[0]
			        x[-4] = 'a'; // Same as a[1]
			        x[-3] = 'p'; // Same as a[2]
			        x[-2] = 't'; // Same as a[3]
			        x[-1] = 'a'; // Same as a[4]
			        x[0]  = 'p'; // Same as a[5]
			        x[1]  = '4'; // Same as a[6]
			        x[2]  = '5'; // Same as a[7]
			        x[3]  = '6'; // Same as a[8]
			}

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Note the relative access mechanism used inside function ``fun``

		* See full program below

		.. code-block:: c

			#include <stdio.h>
			#include <string.h>

			void fun(char *x)
			{
			        printf("x = %s\n", x);

			        x[-5] = 'b'; // Same as a[0]
			        x[-4] = 'a'; // Same as a[1]
			        x[-3] = 'p'; // Same as a[2]
			        x[-2] = 't'; // Same as a[3]
			        x[-1] = 'a'; // Same as a[4]
			        x[0]  = 'p'; // Same as a[5]
			        x[1]  = '4'; // Same as a[6]
			        x[2]  = '5'; // Same as a[7]
			        x[3]  = '6'; // Same as a[8]
			}

			int main(void)
			{
			        char a[10] = "Laptop123";

			        fun(a + 5);

			        printf("a = %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			x = p123
			a = baptap456

.. _funcs_n_ptrs_char_sd_array_ex_14:

.. tab-set::

        .. tab-item:: Example 7 : Address of full array and Pointer to an Array

		* Step 1 : Consider a character array

		.. code-block:: c

			char a[10] = "Laptop123";

		* Step 2 : Pass the address of array ``a`` to function ``fun``

		.. code-block:: c

		        fun(&a);

		* Step 3 : Define the function ``fun``

		.. code-block:: c

			void fun( char (*ptr)[10] )
			{       

			}

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Note that ``char (*ptr)[10]`` is pointer to an array of 10 characters

		.. panels::
			:container: container pb-4
			:column: col-lg-12 p-2
			:card: shadow

			Which means incrementing ``ptr`` will increment by 10 Bytes and decrementing ``ptr`` will decrement by 10 Bytes

		* Step 4 : Access full string inside function ``fun``

		.. code-block:: c

			void fun( char (*ptr)[10] )
			{       
			        printf("fun : String is %s\n", *ptr);

			        // Change full string
			        strcpy(*ptr, "Laptop456");
			}

		* Step 5 : Access individual characters inside function ``fun``

		.. code-block:: c

			void fun( char (*ptr)[10] )
			{       
			        //Change individual characters
			        (*ptr)[0] = 'g';
			        (*ptr)[1] = 'a';
			        (*ptr)[2] = 'p';
			        (*ptr)[3] = 't';
			        (*ptr)[4] = 'a';
			        (*ptr)[5] = 'p';
			        (*ptr)[6] = '4';
			        (*ptr)[7] = '5';
			        (*ptr)[8] = '6';
			        (*ptr)[9] = '\0';
			}


		* See the full program below

		.. code-block:: c

			#include <stdio.h>
			#include <string.h>

			void fun( char (*ptr)[10] )
			{       
			        printf("fun : String is %s\n", *ptr);

			        // Change full string
			        strcpy(*ptr, "Laptop456");

			        //Change individual characters
			        (*ptr)[0] = 'g';
			        (*ptr)[1] = 'a';
			        (*ptr)[2] = 'p';
			        (*ptr)[3] = 't';
			        (*ptr)[4] = 'a';
			        (*ptr)[5] = 'p';
			        (*ptr)[6] = '4';
			        (*ptr)[7] = '5';
			        (*ptr)[8] = '6';
			        (*ptr)[9] = '\0';
			}

			int main(void)
			{
			        char a[10] = "Laptop123";

			        fun(&a);

			        printf("main : String is %s\n", a);

			        return 0;
			}

		* Output is as below

		.. code-block:: c

			fun  : String is Laptop123
			main : String is gaptap456

.. card:: See Also

	* Other topics of character and functions

		* :doc:`./char`
		* :doc:`./char_sd_array`
		* :doc:`./char_dd_array`
		* :doc:`./char_td_array`
		* :doc:`./char_sp`
		* :doc:`./char_dp`
		* :doc:`./char_tp`

        * Current Module

                * :doc:`../funcs_n_ptrs`

        * Previous Module

                * :doc:`../../typecasting_n_ptr/typecasting_n_ptr`

        * Next Module

                * :doc:`../../memcpy_ptr/memcpy_ptr`

        * Other Modules

                * :doc:`../../variable_and_ptr/variable_and_ptr`
                * :doc:`../../array_n_ptrs/array_n_ptrs`
                * :doc:`../../malloc_ptr/malloc_ptr`
                * :doc:`../../const_ptr/const_ptr`
                * :doc:`../../void_ptr/void_ptr`
                * :doc:`../../array_of_ptr/array_of_ptr`
                * :doc:`../../ptr_to_array/ptr_to_array`
                * :doc:`../../function_ptr/function_ptr`
                * :doc:`../../pre_incr_ptr/pre_incr_ptr`
                * :doc:`../../post_incr_ptr/post_incr_ptr`
                * :doc:`../../pre_decr_ptr/pre_decr_ptr`
                * :doc:`../../post_decr_ptr/post_decr_ptr`